com.day.cq.jcr.adapter
Class ContainerListAdapter

java.lang.Object
  com.day.cq.jcr.adapter.ContentElementAdapter
      com.day.cq.jcr.adapter.StructuredContentElement
          com.day.cq.jcr.adapter.ContainerListAdapter

All Implemented Interfaces:

ContainerList, ContentElement

public class ContainerListAdapter
extends StructuredContentElement
implements ContainerList

The ContainerListAdapter class implements the ContainerList interface on top of the JCR repository.

NOTE: Most of the code in this class has been copied from the original ContainerListProxy class with adaptions to the JCR API and removing references to the stubs used by the ContentBus implementation.

Instances of this class should be used for short-lived objects only, as this class caches information found at access and never checks with the repository whether the information is still accurate on later accesses.

Since:

iguana

Version:

$Rev: 42581 $, $Date: 2008-10-07 14:57:50 +0200 (Tue, 07 Oct 2008) $

Author:

fmeschbe, pkoch

Nested Class Summary

protected static class

ContainerListAdapter.ContainerIteratorImpl This class implements a ContainerIterator that provides the containers stored in the container list

Field Summary

Fields inherited from class com.day.cq.jcr.adapter.ContentElementAdapter

page, parent

Constructor Summary

protected

ContainerListAdapter(PageAdapter page, StructuredContentElement parent, java.lang.String label, ElementInfo elementInfo) Creates a new instance of this class backed by the given node.

Method Summary

void	accept(ContentElementVisitor visitor) Calls the ContentElementVisitor.visit(Container) method with this as its parameter.
void	clear() Removes all containers from this container list.
ContainerIterator	containerIterator() Returns a ContainerIterator to iterate over all containers contained in this container list.
void	copyTo(ContentElement dst) Recursively copies the containers in this container list to the destination container list.
Container	createContainer() Creates a container with an autmoatically generated container label.
Container	createContainer(java.lang.String label, java.lang.String above) Creates a new container with the exact label.
Container	createContainer(java.lang.String labelhint, java.lang.String above, boolean exact) Creates a new container whose label is derived from the given labelhint.
Container	getContainer(int index) Returns the container with given numeric index.
Container	getContainer(java.lang.String label) Returns the Container with the given label.
Container	getContainer(java.lang.String label, boolean create) Returns the container with the given label, optionally creating the container if not existing.
protected ContentElement	getDeepElement(java.util.StringTokenizer labels, boolean create) Accesses the child content element named by the first token in labels and either returns that child element if the labels do not contain more tokens or returns the result of forwarding to the child element's getDeepElement method.
ContentElement	getElement(java.lang.String label) Returns the content element with the given label.
protected java.lang.String	getNodeType() Returns Util.NODE_CONTAINERLIST_TYPE as the name of the node type for nodes representing container lists.
boolean	hasContainer(java.lang.String label) Returns whether this container list has a content element with the given label.
boolean	hasElement(java.lang.String label) Returns whether this container list has a content element with the given label.
boolean	isEmpty() Checks, if this container list is empty, i.e.
boolean	isReadOnly() Returns true if this container list has been defined as read-only in the CSD.
void	moveContainer(java.lang.String label, java.lang.String above) Moves a Container to a new location.
void	removeContainer(java.lang.String label) Removes the Container specified by label from this containerlist.
int	size() Returns the number of containers in this container list.
protected Container	wrapContainerNode(java.lang.String label, javax.jcr.Node containerNode) Returns a Container based on the given container node with the defined label.

Methods inherited from class com.day.cq.jcr.adapter.StructuredContentElement

getItemName

Methods inherited from class com.day.cq.jcr.adapter.ContentElementAdapter

canModify, getDeepElement, getDeepElement, getElementInfo, getLabel, getModificationTime, getPage, getQualident, getUUID, parent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.day.cq.contentbus.ContentElement

getDeepElement, getDeepElement, getLabel, getModificationTime, getQualident, getUUID, parent

Constructor Detail

ContainerListAdapter

protected ContainerListAdapter(PageAdapter page,
                               StructuredContentElement parent,
                               java.lang.String label,
                               ElementInfo elementInfo)

Creates a new instance of this class backed by the given node.

Parameters:

page - The ContentBus page on which this container list is located.

parent - The content element in which this container list is located as a direct child element.

label - The label of this container list.

elementInfo - The container list definition.

Method Detail

hasElement

public boolean hasElement(java.lang.String label)

Returns whether this container list has a content element with the given label. This method returns the same value as calling hasContainer(String).

This method is implemented by calling the hasContainer(String) method.

Specified by:

hasElement in interface ContentElement

Returns:

true if it exists; false otherwise.

getElement

public ContentElement getElement(java.lang.String label)
                          throws NoSuchContentElementException,
                                 ContentBusException

Returns the content element with the given label. This method returns the same result as the getContainer(String) method.

This method is implemented by calling the getContainer(String) method.

Specified by:

getElement in interface ContentElement

Parameters:

label - The name of the direct-child content element to return.

Returns:

The named content element.

Throws:

NoSuchContentElementException - If this container list has no container with the given label.

ContentBusException - if an error occurrs

hasContainer

public boolean hasContainer(java.lang.String label)

Returns whether this container list has a content element with the given label.

Specified by:

hasContainer in interface ContainerList

Parameters:

label - the label of a container

Returns:

true if the container exists; false otherwise;

getContainer

public Container getContainer(java.lang.String label,
                              boolean create)
                       throws ContentBusException

Returns the container with the given label, optionally creating the container if not existing.

Specified by:

getContainer in interface ContainerList

Parameters:

label - The label of the container to return.

create - true if the container should be created if not yet existing.

Returns:

The named container or null if this container list does not contain such a container and create is false or if this container list is read-only.

Throws:

java.lang.IllegalStateException - If the container should be created but the page on which this container list is located is not in transaction.

ContentBusException - If any other error occurrs accessing the named container or creating a new container.

getContainer

public Container getContainer(java.lang.String label)
                       throws NoSuchContentElementException,
                              ContentBusException

Returns the Container with the given label. This implementation wraps child node with the given label in a ContainerAdapter instance assuming that each child node of the node backing this container list is backing a container.

Specified by:

getContainer in interface ContainerList

Parameters:

label - the label of the desired container

Returns:

the desired container

Throws:

NoSuchContentElementException - if the container does not exist

ContentBusException - if an error occurrs

getContainer

public Container getContainer(int index)
                       throws NoSuchContentElementException,
                              ContentBusException

Returns the container with given numeric index. Counting starts at zero with the first container following the container sort order.

Specified by:

getContainer in interface ContainerList

Parameters:

index - The numeric index of the container to return.

Returns:

The container with the given numeric index within this container list.

Throws:

NoSuchContentElementException - If the index is higher than the number of containers in this container list.

ContentBusException - If any other error occurrs trying to access the container.

containerIterator

public ContainerIterator containerIterator()
                                    throws ContentBusException

Returns a ContainerIterator to iterate over all containers contained in this container list.

Specified by:

containerIterator in interface ContainerList

Returns:

a ContainerIterator.

Throws:

ContentBusException - if an error occurrs preparing the container iterator.

size

public int size()

Returns the number of containers in this container list. This implementation returns the number of child nodes, which are expected to all represent containers of this container list.

Specified by:

size in interface ContainerList

Returns:

the number of containers in the list

getDeepElement

protected ContentElement getDeepElement(java.util.StringTokenizer labels,
                                        boolean create)
                                 throws NoSuchContentElementException,
                                        ContentBusException

Accesses the child content element named by the first token in labels and either returns that child element if the labels do not contain more tokens or returns the result of forwarding to the child element's getDeepElement method.

Specified by:

getDeepElement in class ContentElementAdapter

Parameters:

labels - The tokenized qualident of the ultimate content element to find.

create - true if the method is allowed to create intermediate content elements if missing.

Returns:

The content element found for the qualident represented by labels.

Throws:

NoSuchContentElementException - Is thrown if the first token in labels does not refer to an existing child content element of this container and create is false or this container list is read-only.

ContentBusException - Is thrown if any other error occurrs drilling down the content element tree.

getNodeType

protected java.lang.String getNodeType()

Returns Util.NODE_CONTAINERLIST_TYPE as the name of the node type for nodes representing container lists.

Specified by:

getNodeType in class StructuredContentElement

createContainer

public Container createContainer()
                          throws ContentBusException

Creates a container with an autmoatically generated container label.

This implementation uses a global instance of the java.util.Random class to get approximately equally distributed numeric labels in the range between 0 (inclusive) and 100'000 (exclusive). The reason to use this pseudo-random number generator is to try to prevent too many checks for label duplicate because each check results in a container node access check. As the label has no significance as to the container ordering, this is not a big issue.

If the number of containers gets close to the maximum number (100'000) it tends to take longer to find a "free" number. To prevent to long processing times a limit is built in which limits the number of loop iterations to 1000 times the maximum number (100'000'000). If this number of iterations is reached without finding a "free" number a ContentBusException is thrown.

After having found a non-existant label, this method calls getContainer(newLast, null, true), where newLast is the label found in the first step.

Specified by:

createContainer in interface ContainerList

Returns:

the newly created container

Throws:

java.lang.IllegalStateException - If the page on which this container list is located is not in transaction.

ContentBusException - If any other error occurrs creating the new container. Especially this exception may be thrown if no container label may be created in a reasonable amount of processing.

createContainer

public Container createContainer(java.lang.String label,
                                 java.lang.String above)
                          throws ContentBusException

Creates a new container with the exact label. This method is implemented by calling createContainer(label, above, true).

Specified by:

createContainer in interface ContainerList

Parameters:

label - The (exact) label of the new container to create

above - The (optional) label of the container above which the new container is inserted. If this is null, an empty string or not the label of an existing container, the new container is appended to the end of the container list.

Returns:

the newly created container.

Throws:

java.lang.IllegalArgumentException - if the labelhint contains invalid label characters.

ContentBusException - if any error occurrs creating the new container.

createContainer

public Container createContainer(java.lang.String labelhint,
                                 java.lang.String above,
                                 boolean exact)
                          throws ContentBusException

Creates a new container whose label is derived from the given labelhint.

Specified by:

createContainer in interface ContainerList

Parameters:

labelhint - The proposed label of the new container. Depending on the value of the exact parameter, this label may be modified or not to create the real label for the new container.

above - The (optional) label of the container above which the new container is inserted. If this is null, an empty string or not the label of an existing container, the new container is appended to the end of the container list.

exact - Indicates whether the labelhint parameter is to be used as the exact name of the new container (true). Otherwise - if false - the label may be derived from labelhint by modifying it to ensure it contains valid label characters and is a unique label within the container list.

Returns:

The newly created container.

Throws:

java.lang.IllegalArgumentException - if exact is true and the labelhint contains invalid label characters.

ContentBusException - if any error occurrs creating the new container.

moveContainer

public void moveContainer(java.lang.String label,
                          java.lang.String above)
                   throws ContentBusException

Moves a Container to a new location. The page that this container list belongs to, must already be in a transaction. If this container list is defined read only, this method has no effect.

Specified by:

moveContainer in interface ContainerList

Parameters:

label - label of container to move

above - label of container to place above. if this parameter is null or an empty string, the container is moved to the end of the list

Throws:

ContentBusException - if an error occurrs

NoSuchContentElementException - if either the source or above container does not exist.

java.lang.IllegalStateException - if the page is not in a transaction

removeContainer

public void removeContainer(java.lang.String label)
                     throws ContentBusException

Removes the Container specified by label from this containerlist. The page that this container list belongs to, must already be in a transaction. If this container list is defined read only, this method has no effect.

Specified by:

removeContainer in interface ContainerList

Parameters:

label - the label of the container to remove

Throws:

ContentBusException - if an error occurrs

NoSuchContentElementException - if the container does not exist.

java.lang.IllegalStateException - if the page is not in a transaction

clear

public void clear()
           throws ContentBusException

Removes all containers from this container list. On all containers removed the clear method is called to clear out the containers removed. The page which this element belongs to, must already by in a transaction.

Specified by:

clear in interface ContentElement

Throws:

ContentBusException

java.lang.IllegalStateException - if the page is not in a transaction

See Also:

Page#startTransaction()

copyTo

public void copyTo(ContentElement dst)
            throws ContentBusException

Recursively copies the containers in this container list to the destination container list.

This method iteratos over the containers in this container list, creates a like named container in the destination container list and calls the copyTo method on the source container handing the newly created destination container.

Specified by:

copyTo in interface ContentElement

Parameters:

dst - The destination container list into which all containers of this container list are copied.

Throws:

java.lang.ClassCastException - If the dst content element is not ContainerList.

ContentBusException - If an error occurrs such as any container already existing in the destination container list.

isEmpty

public boolean isEmpty()

Checks, if this container list is empty, i.e. has no containers.

Specified by:

isEmpty in interface ContentElement

Returns:

true if this list is empty; false otherwise.

Throws:

ContentBusException - if an error occurrs checking whether any containers exist in this container list.

isReadOnly

public boolean isReadOnly()

Returns true if this container list has been defined as read-only in the CSD.

Specified by:

isReadOnly in interface ContainerList

Overrides:

isReadOnly in class ContentElementAdapter

Returns:

true if this container list is defined as read only; false otherwise.

accept

public void accept(ContentElementVisitor visitor)
            throws ContentBusException

Calls the ContentElementVisitor.visit(Container) method with this as its parameter. It is the task of the called visit method to traverse the content elements of this container.

Specified by:

accept in interface ContentElement

Parameters:

visitor - the visitor to call with this instance.

Throws:

ContentBusException - may be thrown by the visitor's visit method in case of an error, which is forwarded to the caller of this method.

wrapContainerNode

protected Container wrapContainerNode(java.lang.String label,
                                      javax.jcr.Node containerNode)

Returns a Container based on the given container node with the defined label.

Parameters:

label - The labe of the container. This will generally be the same as the name of the containerNode. This should not be the empty string or null, otherwise spurious errors may later occurr.

containerNode - The JCR Node providing the contents of the container.