Overview

Assuming you have successfully obtained/built the Castor Taglib jar and configured your servlet container, you are ready to begin using the tags. The castor-taglib.jar needs to be in your WEB-INF/lib and the castor.tld needs to be in WEB-INF.

At the top of each JSP that uses the library, you need to include the following. 

<%@ taglib uri='/WEB-INF/castor.tld' prefix='castor' %>

Each of the tags is described in detail below. At a glance, the tags are:

  • Jdo
  • Transaction
  • Load
  • Create
  • Delete
  • Update
  • Oql
  • Oql Bind
  • QueryResults

jdo

This tag simply locates a Castor DataObjects instance from JNDI and makes it available as a paged scoped JDO object.

Attribute Description Required Default
id The name of a page scoped variable that the Castor JDO object will be stored as. Yes None
jndiName The JNDI name of a Castor DataObjects instance. Yes None

For example:

<castor:jdo id="myJDO" jndiName="java:comp/env/jdo/CastorJdo" />

transaction

This tag begins and ends a Castor transaction. All other Castor tags must be nested within a Castor transaction tag. It implements the TryCatchFinally interface.

Attribute Description Required Default
name The name of the page scoped JDO object that this transaction will be obtained from. Yes None

For example:

<castor:transaction jdoName="myJDO">
	<!-- other tags -->
</castor:transaction>

load

This tag uses the Castor Database load method to obtain a data object from the database. If the object is not found, a new instance of the data object class is returned instead.

Attribute Description Required Default
id The name of a variable that the data object retrieved will be stored as. The scope of this variable is determined by the scope attribute below. Yes None
className The class name of the data object to be retrieved. Yes None
key The primary key of the data object in persistent storage. Supports EL. Yes None
scope The scope of the variable: either page, request, session or application. No page
accessMode The transaction mode. Can be either Shared, DbLocked, Exclusive or ReadOnly. Refer to the documentation for the Castor Database API. Not all access modes are well supported by all databases. No Shared

For example:

<castor:transaction jdoName="myJDO">
	<castor:load id="client" className="com.fc.example.data.ClientData" key="123" />
</castor:transaction>

Or using EL to find the primary key from the request:

<castor:transaction jdoName="myJDO">
	<castor:load id="client" className="com.fc.example.data.ClientData" key="${param.clientId}" />
</castor:transaction>

create

This tag uses the Castor Database create method to create a new data object in the database.

Attribute Description Required Default
name The name of the page scoped object to be created in persistent storage. Yes None

For example:

<castor:transaction jdoName="myJDO">
	<castor:create name="project" />
</castor:transaction>

delete

This tag uses the Castor Database remove() method to remove a data object in the database.

Attribute Description Required Default
name The name of the page scoped object to be removed from persistent storage. Yes None

For example:

<castor:transaction jdoName="myJDO">
	<castor:delete name="project" />
</castor:transaction>

update

This tag uses the Castor Database update() method to create a data object that was loaded or queried in a different transaction. The data object must implement the Castor TimeStampable interface to support long transactions.

Attribute Description Required Default
name The name of the page scoped object to be updated in persistent storage. Yes None

For example:

<castor:transaction jdoName="myJDO">
	<castor:update name="project" />
</castor:transaction>

oql

This tag retrieves an OqlQuery object from the Castor Database object. It must be nested within a transaction tag. It can have "bind" and "results" tags nested within it.

Attribute Description Required Default
query A string representing the oql to be performed. Yes None

For example:

	<castor:oql query="SELECT p FROM com.fc.example.data.ClientData p">
			<p>An example of a query with parameters (see "bind" below):</p>

<castor:oql query="SELECT p FROM com.fc.example.data.ClientData p WHERE p.current=$1" >

bind

This tag binds a parameter to an OqlQuery object. One or more must be nested within an oql tag where the query has parameters. The number of bind tags must match the number of query parameters.

Attribute Description Required Default
value The name of a page scoped object to bind to the query. Can be evaluated from an EL expression. Yes None

For example:

<castor:bind value="fred" />

Using an EL expression:

<castor:bind value="${param.current}" />

results

This tag creates a QueryResults object by executing the oql query in the enclosing oql tag. It extends IterationTag.

Attribute Description Required Default
id Each result will be placed in a page scoped variable with this name. Yes None
indexId The name of a page scope integer representing the index of the iterator. No None
size If the results are to be revealed in "pages", this determines the size of each page. If it is set, so must page. Can be the result of evaluating an EL expression. No None
page If the results are paged, this represents the current page we are on. If it is set, so must size. Can be the result of evaluating an EL expression. No None
accessMode The transaction mode. Can be either Shared, DbLocked, Exclusive or ReadOnly. Refer to the documentation for the Castor Database API. Not all access modes are well supported by all databases. No Shared

For example:

<castor:transaction jdoName="myJDO">
	<castor:oql query="SELECT p FROM com.fc.example.data.ClientData p WHERE p.current=$1" >
		<castor:bind value="${param.current}" />
		<castor:results id="result" page="${page}" size="${size}" indexId="index" accessMode="ReadOnly">
			<c:out value="${result.id}"/>
		</castor:results>		
	</castor:oql>
</castor:transaction>