Introduction   Tag Summary   Container Tags   Worker Tags  

The Xephyrus Data Structures Tag Library (das) provides an easy way to create and manipulate the contents of common Java data-structures such as maps and lists using JSP tags.

A container tag defines a data structure object. The objects underlying these tags store data to be accessed and manipulated by worker tags.

References a map. A map is a container that maps keys to values.

If the map does not already exist, it will be created. Any map created by this tag will implement the Map interface. Similarly, any map previously created and referenced by this tag must implement the Map interface.

If the sorted attribute is specified any existing map object will be imported to a SortedMap object. Sorting will be performed on the keys only, not the values. The keys will be converted to String objects for sorting.

If a file is specified, the path given can be absolute, relative to the current working directory, or relative to the current servlet context. An absolute path starts with a / (slash). A path relative to the current servlet context starts with a ~ (tilde). Any path starting with any other character is considered relative to the current working directory. Note that this is likely to vary depending on your web server.

When a file is specified to be loaded into a map the file must follow the format of:

key field-delimiter value record-delimiter

The key can be any number of any characters except the field-delimiter characters. The first field-delimiter character that is encountered terminates the key.

The field-delimiter can be one of these: = (equal sign), : (colon) or /t (tab). Once a single field-delimiter has been encountered subsequent field-delimiter characters will be dropped until the first non-field-delimiter character is encountered.

The value can be any number of any characters except the record-delimiter characters. The first record-delimiter character that is encountered terminates the value.

The record-delimiter can be one of these: /n (new line) or /r (carriage return). Once a single record-delimiter has been encountered subsequent record-delimiter characters will be dropped until the first non-record-delimiter character is encountered.

This cycle will continue until the entire file has been read and loaded. If the last character read in the file is in a key and there is no value for that key, an empty String will be added to the Map as the value for that key.

References a list. A list is an object that holds an ordered collection of values.

If the list does not exist, it will be created. Any list created by this tag will implement the Collection interface. Similarly, any list previously created and referenced by this tag must implement the Collection interface.

If the sorted attribute is specified any existing list object will be imported to a SortedSet object. Sorting will be performed on the values as they are added to the list. The values will be converted to String objects for sorting.

If a file is specified, the path given can be absolute, relative to the current working directory, or relative to the current servlet context. An absolute path starts with a / (slash). A path relative to the current servlet context starts with a ~ (tilde). Any path starting with any other character is considered relative to the current working directory. Note that this is likely to vary depending on your web server.

When a file is specified to be loaded into a list each individual line in a file will be considered to be a separate value in the list. A line is considered to be any string terminated by any combination of: \n (new line) and \r (carriage return).

A worker tag performs some task on a data structure object. Worker tags can access or manipulate the data stored in the data structure objects underlying container tags. All worker tags must be nested within a container tag.

Sets a value in a container.

The value can be set through the 'value' attribute, or specified as the body of the tag. If both are present, the 'value' attribute will be used. The body of the tag does not do expression language evaluation.

If the container is a map the key must be specified. If the specified key already exists the previous value will be removed before this new value is set. If the given value is a delimited list of values a list object will be created, all the given values will be added to that list in the order specified, and that list will be set as the value of the key.

If the container is a list every value specified, in a delimited list or not, will be added to the container list as an individual element. If an index if given that element will be removed before the new element or elements are added, but the new elements will be added at the end of the list unless it is a sorted list.

Adds a value to a container.

The value can be set through the 'value' attribute, or specified as the body of the tag. If both are present, the 'value' attribute will be used. The body of the tag does not do expression language evaluation.

If the container is a map the key must be specified. If the specified key already exists the previous value will be converted to a list (if it was not already one) and both the previous and new values will be added to that list. If the given value is a delimited list of values all those values will be added to the list. That list will then be set as the value of the key.

If the container is a list every value specified, in a delimited list or not, will be added to the container list as an individual element.

Retrieves a value from a container. A single value can be specified for retrieval or each value in the container can be retrieved.

If a specific value is desired and the container is a map the key attribute should be specified. Similarly, if the container is a list the index attribute should be specified.

If the var or id attributes are set the retrieved value will be stored in a context variable with the name specified by those attributes. If both attributes are set the value of the var attribute will be used as the name. If none are set the retrieved value will be written to the output stream for the page request.

If every value is desired the loop attribute should be specified. The loop attribute can also be used to loop through multiple values for a key, if a key has multiple values. Using the loop on a single value will not cause any adverse affects.

When looping the body of the get tag will be evaluated once for every iteration of the loop. Note that if there are no values in the container the body of the get tag will not be evaluated (or, more accurately, will be evaluated zero times).

If a context variable is specified via the var or id attributes that variable will contain one value during each iteration of the loop. The values will be provided in the order they are stored in the container, which may or may not be sorted.

After the evaluation of the tag, including all looping, the specified variable will contain the last value retrieved.

Removes a value from a container.

If the var or id attributes are set the removed value will be stored in a context variable with the name specified by those attributes. If both attributes are set the value of the var attribute will be used as the name. If none are set the removed value will be written to the output stream for the page request.

Retrieves the number of elements in the container.

For maps this size will be the number of keys, not the number of values. The number of values is guaranteed to be the same or greater as the number of keys. For lists this size is simply the element count.

If the var or id attributes are set the size of the container will be stored in a context variable with the name specified by those attributes. If both attributes are set the value of the var attribute will be used as the name. If none are set the size will be written to the output stream for the page request.