From 544a4770365be51e26b1b8418f2f4226db5bcb15 Mon Sep 17 00:00:00 2001 From: Jani Laakso Date: Thu, 12 Apr 2007 14:41:25 +0000 Subject: Pulled changesets from branches/4.0.0-SRIT into trunk, done by mohamed.atique@renaissance-it.com. All changes are related to javadocs only. Merge was done beetween revisions 924:1192. svn changeset:1212/svn branch:trunk --- src/com/itmill/toolkit/data/Buffered.java | 90 ++++-- .../itmill/toolkit/data/BufferedValidatable.java | 20 +- src/com/itmill/toolkit/data/Container.java | 65 +++-- src/com/itmill/toolkit/data/Item.java | 89 +++--- src/com/itmill/toolkit/data/Property.java | 161 +++++++---- src/com/itmill/toolkit/data/Validatable.java | 56 +++- src/com/itmill/toolkit/data/Validator.java | 33 ++- src/com/itmill/toolkit/data/util/BeanItem.java | 47 +++- .../data/util/ContainerHierarchicalWrapper.java | 132 ++++++--- .../toolkit/data/util/ContainerOrderedWrapper.java | 155 +++++++---- .../toolkit/data/util/FilesystemContainer.java | 217 ++++++++++----- .../toolkit/data/util/HierarchicalContainer.java | 81 +++--- .../itmill/toolkit/data/util/IndexedContainer.java | 256 ++++++++++------- .../itmill/toolkit/data/util/MethodProperty.java | 308 +++++++++++++-------- .../itmill/toolkit/data/util/ObjectProperty.java | 125 +++++---- .../itmill/toolkit/data/util/PropertysetItem.java | 66 ++++- .../itmill/toolkit/data/util/QueryContainer.java | 217 ++++++--------- .../toolkit/data/validator/CompositeValidator.java | 85 ++++-- .../toolkit/data/validator/NullValidator.java | 40 ++- .../data/validator/StringLengthValidator.java | 77 +++--- 20 files changed, 1437 insertions(+), 883 deletions(-) (limited to 'src/com/itmill/toolkit/data') diff --git a/src/com/itmill/toolkit/data/Buffered.java b/src/com/itmill/toolkit/data/Buffered.java index 0e14fdd8c6..fcba99d313 100644 --- a/src/com/itmill/toolkit/data/Buffered.java +++ b/src/com/itmill/toolkit/data/Buffered.java @@ -33,22 +33,29 @@ import com.itmill.toolkit.terminal.PaintException; import com.itmill.toolkit.terminal.PaintTarget; import com.itmill.toolkit.terminal.SystemError; -/**

Defines the interface to commit and discard changes to an object, - * supporting read-through and write-through modes.

+/** + *

Defines the interface to commit and discard changes to an object, + * supporting read-through and write-through modes. + *

* *

Read-through mode means that the value read from the buffered * object is constantly up to date with the data source. * Write-through mode means that all changes to the object are - * immediately updated to the data source.

+ * immediately updated to the data source. + *

* *

Since these modes are independent, their combinations may result in - * some behaviour that may sound surprising. For example, if a - * Buffered object is in read-through mode but not in - * write-through mode, the result is an object whose value is updated + * some behaviour that may sound surprising. + *

+ * + *

+ * For example, if a Buffered object is in read-through mode + * but not in write-through mode, the result is an object whose value is updated * directly from the data source only if it's not locally modified. If the * value is locally modified, retrieving the value from the object would * result in a value that is different than the one stored in the data - * source, even though the object is in read-through mode.

+ * source, even though the object is in read-through mode. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -56,7 +63,8 @@ import com.itmill.toolkit.terminal.SystemError; */ public interface Buffered { - /** Updates all changes since the previous commit to the data source. + /** + * Updates all changes since the previous commit to the data source. * The value stored in the object will always be updated into the data * source when commit is called. * @@ -66,7 +74,8 @@ public interface Buffered { */ public void commit() throws SourceException; - /** Discards all changes since last commit. The object updates its value + /** + * Discards all changes since last commit. The object updates its value * from the data source. * * @throws SourceException if the operation fails because of an @@ -75,7 +84,8 @@ public interface Buffered { */ public void discard() throws SourceException; - /** Tests if the object is in write-through mode. If the object is in + /** + * Tests if the object is in write-through mode. If the object is in * write-through mode, all modifications to it will result in * commit being called after the modification. * @@ -84,42 +94,51 @@ public interface Buffered { */ public boolean isWriteThrough(); - /** Sets the object's write-through mode to the specified status. When - * switching the write-through mode on, the commit() + /** + * Sets the object's write-through mode to the specified status. When + * switching the write-through mode on, the commit * operation will be performed. * * @param writeThrough Boolean value to indicate if the object should be * in write-through mode after the call. + * @throws SourceException + * If the operation fails because of an exception + * is thrown by the data source. + * */ public void setWriteThrough(boolean writeThrough) throws SourceException; - /** Tests if the object is in read-through mode. If the object is in + /** + * Tests if the object is in read-through mode. If the object is in * read-through mode, retrieving its value will result in the value - * being first updated from the data source to the object. The only - * exception to this rule is that when the object is not in + * being first updated from the data source to the object. + *

+ * The only exception to this rule is that when the object is not in * write-through mode and it's buffer contains a modified value, the * value retrieved from the object will be the locally modified value * in the buffer which may differ from the value in the data source. - * + *

* @return true if the object is in read-through mode, * false if it's not. */ public boolean isReadThrough(); - /** Sets the object's read-through mode to the specified status. When + /** + * Sets the object's read-through mode to the specified status. When * switching read-through mode on, the object's value is updated from * the data source. * * @param readThrough Boolean value to indicate if the object should be * in read-through mode after the call. * - * @throws SourceException if the operation fails because of an + * @throws SourceException If the operation fails because of an * exception is thrown by the data source. The cause is included in the * exception. */ public void setReadThrough(boolean readThrough) throws SourceException; - /** Tests if the value stored in the object has been modified since it + /** + * Tests if the value stored in the object has been modified since it * was last updated from the data source. * * @return true if the value in the object has been @@ -128,8 +147,10 @@ public interface Buffered { */ public boolean isModified(); - /** An exception that signals that one or more exceptions occurred - * while a buffered object tried to access its data source. + /** + * An exception that signals that one or more exceptions occurred + * while a buffered object tried to access its data source + * or if there is a problem in processing a data source. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 @@ -150,7 +171,8 @@ public interface Buffered { private Throwable[] causes = { }; - /** Creates a source exception that does not include a cause. + /** + * Creates a source exception that does not include a cause. * * @param source the source object implementing the Buffered interface. */ @@ -158,7 +180,8 @@ public interface Buffered { this.source = source; } - /** Creates a source exception from a cause exception. + /** + * Creates a source exception from a cause exception. * * @param source the source object implementing the Buffered * interface. @@ -169,7 +192,8 @@ public interface Buffered { causes = new Throwable[] { cause }; } - /** Creates a source exception from multiplse causes. + /** + * Creates a source exception from multiple causes. * * @param source the source object implementing the Buffered * interface. @@ -180,7 +204,8 @@ public interface Buffered { this.causes = causes; } - /** Get the cause of the exception. + /** + * Gets the cause of the exception. * * @return The cause for the exception. * @throws MoreThanOneCauseException if there is more than one cause @@ -193,7 +218,8 @@ public interface Buffered { return causes[0]; } - /** Get all the causes for this exception. + /** + * Gets all the causes for this exception. * * @return throwables that caused this exception */ @@ -201,7 +227,8 @@ public interface Buffered { return causes; } - /** Get the source of the exception. + /** + * Gets the source of the exception. * * @return the Buffered object which generated this exception. */ @@ -209,12 +236,15 @@ public interface Buffered { return source; } - /** Get the error level of this buffered source exception. The + /** + * Gets the error level of this buffered source exception. The * level of the exception is maximum error level of all the contained - * causes. The causes that do not specify error level default to + * causes. + *

+ * The causes that do not specify error level default to * ERROR level. Also source exception without any causes * are of level ERROR. - * + *

* @see com.itmill.toolkit.terminal.ErrorMessage#getErrorLevel() */ public int getErrorLevel() { diff --git a/src/com/itmill/toolkit/data/BufferedValidatable.java b/src/com/itmill/toolkit/data/BufferedValidatable.java index f5cc18f0de..de3a6edac5 100644 --- a/src/com/itmill/toolkit/data/BufferedValidatable.java +++ b/src/com/itmill/toolkit/data/BufferedValidatable.java @@ -29,9 +29,11 @@ package com.itmill.toolkit.data; -/**

This interface defines the combination of Validatable and Buffered interfaces. - * The combination of the interfaces defines if the invalid data is committed to - * datasource.

+/**

+ * This interface defines the combination of Validatable and + * Buffered interfaces. The combination of the interfaces defines + * if the invalid data is committed to datasource. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -39,11 +41,15 @@ package com.itmill.toolkit.data; */ public interface BufferedValidatable extends Buffered, Validatable { - /** Is the invalid data committed to datasource. - * The default is false. */ + /** + * Tests if the invalid data is committed to datasource. + * The default is false. + */ public boolean isInvalidCommitted(); - /** Set if the invalid data should be committed to datasource. - * The default is false. */ + /** + * Sets if the invalid data should be committed to datasource. + * The default is false. + */ public void setInvalidCommitted(boolean isCommitted); } diff --git a/src/com/itmill/toolkit/data/Container.java b/src/com/itmill/toolkit/data/Container.java index 048a5da590..6dd819719b 100644 --- a/src/com/itmill/toolkit/data/Container.java +++ b/src/com/itmill/toolkit/data/Container.java @@ -296,7 +296,7 @@ public interface Container { public boolean isLastId(Object itemId); /** - * Add new item after the given item. + * Adds new item after the given item. *

* Adding an item after null item adds the item as first item of the * ordered container. @@ -311,7 +311,7 @@ public interface Container { throws UnsupportedOperationException; /** - * Add new item after the given item. + * Adds new item after the given item. *

* Adding an item after null item adds the item as first item of the * ordered container. @@ -334,13 +334,13 @@ public interface Container { /** * Sort method. * - * Sort the container items. + * Sorts the container items. * * @param propertyId * Array of container property IDs, which values are used to * sort the items in container as primary, secondary, ... * sorting criterion. All of the item IDs must be in the - * collection returned by getSortableContainerPropertyIds() + * collection returned by getSortableContainerPropertyIds * @param ascending * Array of sorting order flags corresponding to each property ID * used in sorting. If this array is shorter than propertyId array, @@ -352,7 +352,7 @@ public interface Container { void sort(Object[] propertyId, boolean[] ascending); /** - * Get the container property IDs, which can be used to sort the item. + * Gets the container property IDs, which can be used to sort the item. * * @return The sortable field ids. */ @@ -364,8 +364,8 @@ public interface Container { public interface Indexed extends Ordered { /** - * Gets the index of the Item corresponding to itemId. - * The following is true for the returned index: 0 <= index < size(). + * Gets the index of the Item corresponding to the itemId. + * The following is true for the returned index: 0 <= index < size(). * * @param itemId * ID of an Item in the Container @@ -375,8 +375,7 @@ public interface Container { public int indexOfId(Object itemId); /** - * Get the ID of an Item by an index number. The following is true for - * the index: 0 <= index < size(). + * Gets the ID of an Item by an index number. * * @param index * Index of the requested id in the Container @@ -385,7 +384,7 @@ public interface Container { public Object getIdByIndex(int index); /** - * Add new item at given index. + * Adds new item at given index. *

* The indexes of the item currently in the given position and all the * following items are incremented. @@ -399,7 +398,7 @@ public interface Container { public Object addItemAt(int index) throws UnsupportedOperationException; /** - * Add new item at given index. + * Adds new item at given index. *

* The indexes of the item currently in the given position and all the * following items are incremented. @@ -493,8 +492,7 @@ public interface Container { * Container also implements the Managed interface, the * items created with newItem can have children by * default. - *

- * + * * @param itemId * ID of the Item in the container whose child capability is * to be tested @@ -509,8 +507,10 @@ public interface Container { * Sets the given Item's capability to have children. If the Item * identified with itemId already has children and * areChildrenAllowed is false this method fails and - * false is returned; the children must be first - * explicitly removed with + * false is returned. + *

+ *

+ * The children must be first explicitly removed with * {@link #setParent(Object itemId, Object newParentId)}or * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}. *

@@ -575,7 +575,7 @@ public interface Container { public interface Viewer { /** - * Set the Container that serves as the data source of the viewer. + * Sets the Container that serves as the data source of the viewer. * * @param newDataSource * The new data source Item @@ -583,7 +583,7 @@ public interface Container { public void setContainerDataSource(Container newDataSource); /** - * Get the Container serving as the data source of the viewer. + * Gets the Container serving as the data source of the viewer. * * @return data source Container */ @@ -592,11 +592,15 @@ public interface Container { } /** + *

* Interface implemented by the editor classes supporting editing the * Container. Implementing this interface means that the Container serving - * as the data source of the editor can be modified through it. Note that - * not implementing the Container.Editor interface does not + * as the data source of the editor can be modified through it. + *

+ *

+ * Note that not implementing the Container.Editor interface does not * restrict the class from editing the Container contents internally. + *

*/ public interface Editor extends Container.Viewer { @@ -607,7 +611,7 @@ public interface Container { /** * An Event object specifying the Container whose Item set * has changed. Note that these events are triggered only through succesful - * calls to the newItem() and removeAllItems + * calls to the newItem and removeAllItems * methods in the Container.Managed interface. */ public interface ItemSetChangeEvent { @@ -637,18 +641,19 @@ public interface Container { * listeners. By implementing this interface a class explicitly announces * that it will generate a ItemSetChangeEvent when its * contents are modified. - * - * Note that the general Java convention is not to explicitly declare that a + *

+ * Note: The general Java convention is not to explicitly declare that a * class generates events, but to directly define the * addListener and removeListener methods. * That way the caller of these methods has no real way of finding out if * the class really will send the events, or if it just defines the methods * to be able to implement an interface. + *

*/ public interface ItemSetChangeNotifier { /** - * Adds a Item set change listener for the object. + * Adds an Item set change listener for the object. * * @param listener * listener to be added @@ -656,7 +661,7 @@ public interface Container { public void addListener(Container.ItemSetChangeListener listener); /** - * Removes a Item set change listener from the object. + * Removes the Item set change listener from the object. * * @param listener * listener to be removed @@ -668,9 +673,12 @@ public interface Container { /** * An Event object specifying the Container whose Property - * set has changed. Note that these events are triggered only through - * succesful calls to the addProperty and + * set has changed. + *

+ * Note: These events are triggered only through succesful calls to + * the addProperty and * removeProperty methods in the Container.Managed interface. + *

*/ public interface PropertySetChangeEvent { @@ -699,17 +707,20 @@ public interface Container { } /** + *

* The interface for adding and removing PropertySetChangeEvent * listeners. By implementing this interface a class explicitly announces * that it will generate a PropertySetChangeEvent when its * contents are modified. - * + *

+ *

* Note that the general Java convention is not to explicitly declare that a * class generates events, but to directly define the * addListener and removeListener methods. * That way the caller of these methods has no real way of finding out if * the class really will send the events, or if it just defines the methods * to be able to implement an interface. + *

*/ public interface PropertySetChangeNotifier { diff --git a/src/com/itmill/toolkit/data/Item.java b/src/com/itmill/toolkit/data/Item.java index 04f4488525..d59e94edf4 100644 --- a/src/com/itmill/toolkit/data/Item.java +++ b/src/com/itmill/toolkit/data/Item.java @@ -30,9 +30,12 @@ package com.itmill.toolkit.data; import java.util.Collection; -/**

Provides a mechanism for handling a set of Properties, each associated +/** + *

+ * Provides a mechanism for handling a set of Properties, each associated * to a locally unique identifier. The interface is split into subinterfaces - * to enable a class to implement only the functionalities it needs.

+ * to enable a class to implement only the functionalities it needs. + *

* * @author IT Mill Ltd * @version @VERSION@ @@ -40,7 +43,8 @@ import java.util.Collection; */ public interface Item { - /** Gets the Property corresponding to the given Property ID stored in + /** + * Gets the Property corresponding to the given Property ID stored in * the Item. If the Item does not contain the Property, * null is returned. * @@ -49,62 +53,72 @@ public interface Item { */ public Property getItemProperty(Object id); - /** Gets the collection of IDs of all Properties stored in the Item. + /** + * Gets the collection of IDs of all Properties stored in the Item. * * @return unmodifiable collection containing IDs of the Properties * stored the Item */ public Collection getItemPropertyIds(); - /** Tries to add a new Property into the Item. + /** + * Tries to add a new Property into the Item. * *

This functionality is optional.

* * @param id ID of the new Property - * @param property the Property to be added and associated with - * id - * @throws UnsupportedOperationException if the operation is not supported. + * @param property the Property to be added and associated with the id * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException if the operation is not supported. */ public boolean addItemProperty(Object id, Property property) throws UnsupportedOperationException; - /** Removes the Property identified by ID from the Item. - - *

This functionality is optional.

+ /** + * Removes the Property identified by ID from the Item. + * + *

+ * This functionality is optional. + *

* * @param id ID of the Property to be removed - * @throws UnsupportedOperationException if the operation is not supported. * @return true if the operation succeeded + * @throws UnsupportedOperationException if the operation is not supported. * false if not */ public boolean removeItemProperty(Object id) throws UnsupportedOperationException; - /** Interface implemented by viewer classes capable of using an Item as + /** + * Interface implemented by viewer classes capable of using an Item as * a data source. */ public interface Viewer { - /** Sets the Item that serves as the data source of the viewer. + /** + * Sets the Item that serves as the data source of the viewer. * * @param newDataSource The new data source Item */ public void setItemDataSource(Item newDataSource); - /** Gets the Item serving as the data source of the viewer. + /** + * Gets the Item serving as the data source of the viewer. * * @return data source Item */ public Item getItemDataSource(); } - /** Interface implemented by the editor classes capable of editing the + /** + * Interface implemented by the Editor classes capable of editing the * Item. Implementing this interface means that the Item serving as the - * data source of the editor can be modified through it. Note that - * not implementing the Item.Editor interface does not + * data source of the editor can be modified through it. + *

+ * Note : Not implementing the Item.Editor interface does not * restrict the class from editing the contents of an internally. + *

*/ public interface Editor extends Item.Viewer { @@ -112,54 +126,63 @@ public interface Item { /* Property set change event ******************************************** */ - /** An Event object specifying the Item whose contents - * has been changed through the Property.Managed interface. Note that - * the values stored in the Properties may change without triggering + /** + * An Event object specifying the Item whose contents + * has been changed through the Property interface. + *

+ * Note: The values stored in the Properties may change without triggering * this event. + *

*/ public interface PropertySetChangeEvent { - /** Retrieves the Item whose contents has been modified. + /** + * Retrieves the Item whose contents has been modified. * * @return source Item of the event */ public Item getItem(); } - /** The listener interface for receiving + /** + * The listener interface for receiving * PropertySetChangeEvent objects. */ public interface PropertySetChangeListener { - /** Notifies this listener that the Item's property set has changed. + /** + * Notifies this listener that the Item's property set has changed. * * @param event Property set change event object */ public void itemPropertySetChange(Item.PropertySetChangeEvent event); } - /** The interface for adding and removing - * PropertySetChangeEvent listeners. By implementing this - * interface a class explicitly announces that it will generate a - * PropertySetChangeEvent when its Property set is - * modified. - * - * Note that the general Java convention is not to explicitly declare + /** + * The interface for adding and removing PropertySetChangeEvent + * listeners. By implementing this interface a class explicitly announces that + * it will generate a PropertySetChangeEvent when its Property + * set is modified. + *

+ * Note : The general Java convention is not to explicitly declare * that a class generates events, but to directly define the * addListener and removeListener methods. * That way the caller of these methods has no real way of finding out * if the class really will send the events, or if it just defines the * methods to be able to implement an interface. + *

*/ public interface PropertySetChangeNotifier { - /** Registers a new property set change listener for this Item. + /** + * Registers a new property set change listener for this Item. * * @param listener The new Listener to be registered. */ public void addListener(Item.PropertySetChangeListener listener); - /** Removes a previously registered property set change listener. + /** + * Removes a previously registered property set change listener. * * @param listener Listener to be removed. */ diff --git a/src/com/itmill/toolkit/data/Property.java b/src/com/itmill/toolkit/data/Property.java index 8f5e40a1f3..2f2f27638d 100644 --- a/src/com/itmill/toolkit/data/Property.java +++ b/src/com/itmill/toolkit/data/Property.java @@ -28,60 +28,71 @@ package com.itmill.toolkit.data; -/** Property is a simple data object that contains one typed value. This +/** + *

+ * The Property is a simple data object that contains one typed value. This * interface contains methods to inspect and modify the stored value and its * type, and the object's read-only state. + *

* - * Property also defines the events ReadOnlyStatusChangeEvent and - * ValueChangeEvent, and the associated listener and notifier interfaces. - * - * The Property.Viewer interface should be used to attach the Property to + *

+ * The Property also defines the events ReadOnlyStatusChangeEvent and + * ValueChangeEvent, and the associated listener and notifier interfaces. + *

+ * + *

+ * The Property.Viewer interface should be used to attach the Property to * an external data source. This way the value in the data source can be - * inspected using the Property interface. + * inspected using the Property interface. + *

* - * The Property.editor interface should be implemented if the value needs to + *

+ * The Property.editor interface should be implemented if the value needs to * be changed through the implementing class. - * + *

* @author IT Mill Ltd * @version @VERSION@ * @since 3.0 */ public interface Property { - /** Gets the value stored in the Property. + /** + * Gets the value stored in the Property. * * @return the value stored in the Property */ public Object getValue(); - /** Sets the value of the Property. - * + /** + * Sets the value of the Property. + *

* Implementing this functionality is optional. If the functionality * is missing, one should declare the Property to be in read-only mode - * and throw Property.ReadOnlyException in this function. - * - * It is not required, but highly recommended to support setting + * and throw Property.ReadOnlyException in this function. + *

+ * Note : It is not required, but highly recommended to support setting * the value also as a String in addition to the native * type of the Property (as given by the getType method). * If the String conversion fails or is unsupported, the - * method should throw Property.ConversionException. The + * method should throw Property.ConversionException. The * string conversion should at least understand the format returned by - * the toString() method of the Property. + * the toString method of the Property. * * @param newValue New value of the Property. This should be assignable - * to the type returned by getType, but also String type + * to the type returned by getType, but also String type * should be supported * * @throws Property.ReadOnlyException if the object is in read-only * mode - * @throws Property.ConversionException if newValue can't + * @throws Property.ConversionException if newValue can't * be converted into the Property's native type directly or through * String */ public void setValue(Object newValue) throws Property.ReadOnlyException, Property.ConversionException; - /** Returns the value of the Property in human readable textual format. + /** + * Returns the value of the Property in human readable textual format. * The return value should be assignable to the setValue * method if the Property is not in read-only mode. * @@ -90,7 +101,8 @@ public interface Property { */ public String toString(); - /** Returns the type of the Property. The methods getValue + /** + * Returns the type of the Property. The methods getValue * and setValue must be compatible with this type: one * must be able to safely cast the value returned from * getValue to the given type and pass any variable @@ -100,9 +112,10 @@ public interface Property { */ public Class getType(); - /** Tests if the Property is in read-only mode. In read-only mode calls + /** + * Tests if the Property is in read-only mode. In read-only mode calls * to the method setValue will throw - * ReadOnlyExceptions and will not modify the value of the + * ReadOnlyException and will not modify the value of the * Property. * * @return true if the Property is in read-only mode, @@ -110,16 +123,18 @@ public interface Property { */ public boolean isReadOnly(); - /** Sets the Property's read-only mode to the specified status. + /** + * Sets the Property's read-only mode to the specified status. * * This functionality is optional, but all properties must implement - * the isReadOnly() mode query correctly. + * the isReadOnly mode query correctly. * * @param newStatus new read-only status of the Property */ public void setReadOnly(boolean newStatus); - /** Exception object that signals that a requested + /** + * Exception object that signals that a requested * Property modification failed because it's in read-only mode. * @author IT Mill Ltd. * @version @VERSION@ @@ -132,13 +147,15 @@ public interface Property { */ private static final long serialVersionUID = 3257571702287119410L; - /** Constructs a new ReadOnlyException without a detail + /** + * Constructs a new ReadOnlyException without a detail * message. */ public ReadOnlyException() { } - /** Constructs a new ReadOnlyException with the + /** + * Constructs a new ReadOnlyException with the * specified detail message. * * @param msg the detail message @@ -148,8 +165,9 @@ public interface Property { } } - /** An exception that signals that the value passed to the - * setValue() method couldn't be converted to the native + /** + * An exception that signals that the value passed to the + * setValue method couldn't be converted to the native * type of the Property. * @author IT Mill Ltd * @version @VERSION@ @@ -162,13 +180,15 @@ public interface Property { */ private static final long serialVersionUID = 3257571706666366008L; - /** Constructs a new ConversionException without a + /** + * Constructs a new ConversionException without a * detail message. */ public ConversionException() { } - /** Constructs a new ConversionException with the + /** + * Constructs a new ConversionException with the * specified detail message. * * @param msg the detail message @@ -177,7 +197,8 @@ public interface Property { super(msg); } - /** Constructs a new ConversionException from another + /** + * Constructs a new ConversionException from another * exception. * * @param cause The cause of the the conversion failure @@ -187,7 +208,8 @@ public interface Property { } } - /** Interface implemented by the viewer classes capable of using a + /** + * Interface implemented by the viewer classes capable of using a * Property as a data source. * @author IT Mill Ltd. * @version @VERSION@ @@ -195,25 +217,31 @@ public interface Property { */ public interface Viewer { - /** Set the Property that serves as the data source of the viewer. + /** + * Sets the Property that serves as the data source of the viewer. * * @param newDataSource the new data source Property */ public void setPropertyDataSource(Property newDataSource); - /** Get the Property serving as the data source of the viewer. + /** + * Gets the Property serving as the data source of the viewer. * * @return the Property serving as the viewers data source */ public Property getPropertyDataSource(); } - /** Interface implemented by the editor classes capable of editing the - * Property. Implementing this interface means that the Property serving + /** + * Interface implemented by the editor classes capable of editing the + * Property. + *

+ * Implementing this interface means that the Property serving * as the data source of the editor can be modified through the editor. * It does not restrict the editor from editing the Property internally, * though if the Property is in a read-only mode, attempts to modify it * will result in the ReadOnlyException being thrown. + *

* @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 @@ -224,7 +252,8 @@ public interface Property { /* Value change event ******************************************* */ - /** An Event object specifying the Property whose value + /** + * An Event object specifying the Property whose value * has been changed. * @author IT Mill Ltd. * @version @VERSION@ @@ -232,51 +261,58 @@ public interface Property { */ public interface ValueChangeEvent { - /** Retrieves the Property that has been modified. + /** + * Retrieves the Property that has been modified. * * @return source Property of the event */ public Property getProperty(); } - /** The listener interface for receiving ValueChangeEvent objects. + /** + * The listener interface for receiving ValueChangeEvent objects. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 **/ public interface ValueChangeListener { - /** Notifies this listener that the Property's value has changed. + /** + * Notifies this listener that the Property's value has changed. * * @param event value change event object */ public void valueChange(Property.ValueChangeEvent event); } - /** The interface for adding and removing ValueChangeEvent + /** + * The interface for adding and removing ValueChangeEvent * listeners. If a Property wishes to allow other objects to receive - * ValueChangeEvents generated by it, it must implement + * ValueChangeEvent generated by it, it must implement * this interface. - * - * Note that the general Java convention is not to explicitly declare + *

+ * Note : The general Java convention is not to explicitly declare * that a class generates events, but to directly define the * addListener and removeListener methods. * That way the caller of these methods has no real way of finding out * if the class really will send the events, or if it just defines the * methods to be able to implement an interface. + *

* @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 */ public interface ValueChangeNotifier { - /** Registers a new value change listener for this Property. + /** + * Registers a new value change listener for this Property. * * @param listener the new Listener to be registered */ public void addListener(Property.ValueChangeListener listener); - /** Removes a previously registered value change listener. + /** + * Removes a previously registered value change listener. * * @param listener listener to be removed */ @@ -285,7 +321,8 @@ public interface Property { /* ReadOnly Status change event ***************************************** */ - /** An Event object specifying the Property whose read-only + /** + * An Event object specifying the Property whose read-only * status has been changed. * @author IT Mill Ltd. * @version @VERSION@ @@ -293,14 +330,16 @@ public interface Property { */ public interface ReadOnlyStatusChangeEvent { - /** Property whose read-only state has changed. + /** + * Property whose read-only state has changed. * * @return source Property of the event. */ public Property getProperty(); } - /** The listener interface for receiving ReadOnlyStatusChangeEvent + /** + * The listener interface for receiving ReadOnlyStatusChangeEvent * objects. * @author IT Mill Ltd. * @version @VERSION@ @@ -308,7 +347,8 @@ public interface Property { * */ public interface ReadOnlyStatusChangeListener { - /** Notifies this listener that a Property's read-only status has + /** + * Notifies this listener that a Property's read-only status has * changed. * * @param event Read-only status change event object @@ -317,32 +357,35 @@ public interface Property { Property.ReadOnlyStatusChangeEvent event); } - /** The interface for adding and removing - * ReadOnlyStatusChangeEvent listeners. If a Property - * wishes to allow other objects to receive - * ReadOnlyStatusChangeEvents generated by it, it must + /** + * The interface for adding and removing ReadOnlyStatusChangeEvent + * listeners. If a Property wishes to allow other objects to receive + * ReadOnlyStatusChangeEvent generated by it, it must * implement this interface. - * - * Note that the general Java convention is not to explicitly declare + *

+ * Note : The general Java convention is not to explicitly declare * that a class generates events, but to directly define the * addListener and removeListener methods. * That way the caller of these methods has no real way of finding out * if the class really will send the events, or if it just defines the * methods to be able to implement an interface. + *

* @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 */ public interface ReadOnlyStatusChangeNotifier { - /** Registers a new read-only status change listener for this + /** + * Registers a new read-only status change listener for this * Property. * * @param listener the new Listener to be registered */ public void addListener(Property.ReadOnlyStatusChangeListener listener); - /** Remove a previously registered read-only status change listener. + /** + * Removes a previously registered read-only status change listener. * * @param listener listener to be removed */ diff --git a/src/com/itmill/toolkit/data/Validatable.java b/src/com/itmill/toolkit/data/Validatable.java index 67501c4a0a..b60ee46b54 100644 --- a/src/com/itmill/toolkit/data/Validatable.java +++ b/src/com/itmill/toolkit/data/Validatable.java @@ -30,9 +30,12 @@ package com.itmill.toolkit.data; import java.util.Collection; -/**

Interface for validatable objects. Defines methods to verify if the +/** + *

+ * Interface for validatable objects. Defines methods to verify if the * object's value is valid or not, and to add, remove and list registered - * validators of the object.

+ * validators of the object. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -41,57 +44,86 @@ import java.util.Collection; */ public interface Validatable { - /** Adds a new validator for this object. The validator's + /** + *

+ * Adds a new validator for this object. The validator's * {@link Validator#validate(Object)} method is activated every time the * object's value needs to be verified, that is, when the * {@link #isValid()} method is called. This usually happens when the * object's value changes. + *

* * @param validator the new validator */ void addValidator(Validator validator); - /** Removes a previously registered validator from the object. The - * specified validator is removed from the object and its - * validate method is no longer called in {@link #isValid()}. + /** + *

+ * Removes a previously registered validator from the object. The specified + * validator is removed from the object and its validate method + * is no longer called in {@link #isValid()}. + *

* * @param validator the validator to remove */ void removeValidator(Validator validator); - /** List all validators currently registered for the object. If no + /** + *

+ * Lists all validators currently registered for the object. If no * validators are registered, returns null. + *

* * @return collection of validators or null */ public Collection getValidators(); - /** Tests the current value of the object against all registered + /** + *

+ * Tests the current value of the object against all registered * validators. The registered validators are iterated and for each the * {@link Validator#validate(Object)} method is called. If any validator * throws the {@link Validator.InvalidValueException} this method * returns false. + *

* * @return true if the registered validators concur that * the value is valid, false otherwise */ public boolean isValid(); - /** Checks the validity of the validatable. If the validatable is valid + /** + *

+ * Checks the validity of the validatable. If the validatable is valid * this method should do nothing, and if it's not valid, it should throw * Validator.InvalidValueException + *

* * @throws Validator.InvalidValueException if the value is not valid */ public void validate() throws Validator.InvalidValueException; - /** Does the validabtable object accept invalid values. The default is true. */ + /** + *

+ * Checks the validabtable object accept invalid values.The default value + * is true. + *

+ * + */ public boolean isInvalidAllowed(); - /** Should the validabtable object accept invalid values. Supporting + /** + *

+ * Should the validabtable object accept invalid values. Supporting * this configuration possibility is optional. By default invalid values are - * alloved. + * allowed. + *

+ * + * @param invalidValueAllowed + * + * @throws UnsupportedOperationException + * if the setInvalidAllowed is not supported. */ public void setInvalidAllowed(boolean invalidValueAllowed) throws UnsupportedOperationException; diff --git a/src/com/itmill/toolkit/data/Validator.java b/src/com/itmill/toolkit/data/Validator.java index 4894adce42..9ae86006a7 100644 --- a/src/com/itmill/toolkit/data/Validator.java +++ b/src/com/itmill/toolkit/data/Validator.java @@ -32,7 +32,8 @@ import com.itmill.toolkit.terminal.ErrorMessage; import com.itmill.toolkit.terminal.PaintException; import com.itmill.toolkit.terminal.PaintTarget; -/** Object validator interface. Implementors of this class can be added to +/** + * Object validator interface. Implementors of this class can be added to * any {@link com.itmill.toolkit.data.Validatable} object to verify * its value. The Validatable#isValid(Object) iterates all * registered Validators, calling their {@link #validate(Object)} @@ -46,7 +47,8 @@ import com.itmill.toolkit.terminal.PaintTarget; */ public interface Validator { - /** Checks the given value against this validator. If the value is valid + /** + * Checks the given value against this validator. If the value is valid * this method should do nothing, and if it's not valid, it should throw * Validator.InvalidValueException * @@ -55,12 +57,15 @@ public interface Validator { */ public void validate(Object value) throws Validator.InvalidValueException; - /** Test if the the given value is valid. + /** + * Tests if the given value is valid. * @param value the value to check + * @return true for valid value, otherwise false. */ public boolean isValid(Object value); - /** Adds the proposing functionality to a {@link Validator}. A + /** + * Adds the proposing functionality to a {@link Validator}. A * Suggestive validator can propose a valid value for the * object it is attached to validate. This way the {@link Validatable} * object may avoid situations where it contains a value that could @@ -71,8 +76,9 @@ public interface Validator { */ public interface Suggestive extends Validator { - /** Suggest another value that can be used instead of - * proposedValue if it is invalid. If it is valid + /** + * Suggests another value that can be used instead of the + * proposedValue if it is invalid. If it is valid * in the opinion of this validator, however, it is returned as is. * * @param proposedValue Originally proposed value that could be @@ -82,7 +88,8 @@ public interface Validator { public Object suggestValidValue(Object proposedValue); } - /** Invalid value exception can be thrown by {@link Validator} when a + /** + * Invalid value exception can be thrown by {@link Validator} when a * given value is not valid. * @author IT Mill Ltd. * @version @VERSION@ @@ -99,7 +106,8 @@ public interface Validator { /** Array of validation errors that are causing the problem. */ private InvalidValueException[] causes = null; - /** Constructs a new InvalidValueException with the + /** + * Constructs a new InvalidValueException with the * specified detail message. * * @param message The detail message of the problem. @@ -109,10 +117,11 @@ public interface Validator { }); } - /** Constructs a new InvalidValueException with a set - * of causing validation exceptions. The - * error message contains first the given message and then a list - * of validation errors in the given validatables. + /** + * Constructs a new InvalidValueException with a set + * of causing validation exceptions. The error message contains + * first the given message and then a list of validation errors + * in the given validatables. * * @param message The detail message of the problem. * @param causes Array of validatables whos invalidities are possiblity causing the invalidity. diff --git a/src/com/itmill/toolkit/data/util/BeanItem.java b/src/com/itmill/toolkit/data/util/BeanItem.java index eb7ca89add..4ab7026c10 100644 --- a/src/com/itmill/toolkit/data/util/BeanItem.java +++ b/src/com/itmill/toolkit/data/util/BeanItem.java @@ -37,7 +37,8 @@ import java.util.Iterator; import com.itmill.toolkit.data.Property; -/** A wrapper class for adding the Item interface to any Java Bean. +/** + * A wrapper class for adding the Item interface to any Java Bean. * * @author IT Mill Ltd. * @version @VERSION@ @@ -45,18 +46,26 @@ import com.itmill.toolkit.data.Property; */ public class BeanItem extends PropertysetItem { - /** The bean wich this Item is based on. */ + /** + * The bean which this Item is based on. + */ private Object bean; - /**

Creates a new instance of BeanItem and adds all properties of a + /** + *

+ * Creates a new instance of BeanItem and adds all properties of a * Java Bean to it. The properties are identified by their respective - * bean names.

+ * bean names. + *

+ * + *

+ * Note : This version only supports introspectable bean + * properties and their getter and setter methods. Stand-alone is and + * are methods are not supported. + *

* - *

Note that this version only supports introspectable bean - * properties and their getter and setter methods. Stand-alone "is" and - * "are" methods are not supported.

+ * @param bean the Java Bean to copy properties from. * - * @param bean the Java Bean to copy properties from */ public BeanItem(Object bean) { @@ -83,15 +92,22 @@ public class BeanItem extends PropertysetItem { } } - /**

Creates a new instance of BeanItem and adds all listed properties of a + /** + *

+ * Creates a new instance of BeanItem and adds all listed properties of a * Java Bean to it - in specified order. The properties are identified by their - * respective bean names.

+ * respective bean names. + *

* - *

Note that this version only supports introspectable bean - * properties and their getter and setter methods. Stand-alone "is" and - * "are" methods are not supported.

+ *

+ * Note : This version only supports introspectable bean properties and their getter + * and setter methods. Stand-alone is and are methods + * are not supported. + *

* - * @param bean the Java Bean to copy properties from + * @param bean the Java Bean to copy properties from. + * @param propertyIds + * id of the property. */ public BeanItem(Object bean, Collection propertyIds) { @@ -129,7 +145,8 @@ public class BeanItem extends PropertysetItem { } - /** Get the underlying JavaBean object. + /** + * Gets the underlying JavaBean object. * @return the bean object. */ public Object getBean() { diff --git a/src/com/itmill/toolkit/data/util/ContainerHierarchicalWrapper.java b/src/com/itmill/toolkit/data/util/ContainerHierarchicalWrapper.java index 24adf5672c..b275fb7a22 100644 --- a/src/com/itmill/toolkit/data/util/ContainerHierarchicalWrapper.java +++ b/src/com/itmill/toolkit/data/util/ContainerHierarchicalWrapper.java @@ -39,13 +39,18 @@ import com.itmill.toolkit.data.Container; import com.itmill.toolkit.data.Item; import com.itmill.toolkit.data.Property; -/**

A wrapper class for adding external hierarchy to containers not +/** + *

+ * A wrapper class for adding external hierarchy to containers not * implementing the {@link com.itmill.toolkit.data.Container.Hierarchical} - * interface.

+ * interface. + *

* - *

If the wrapped container is changed directly (that is, not through + *

+ * If the wrapped container is changed directly (that is, not through * the wrapper), the hierarchy information must be updated with the - * {@link #updateHierarchicalWrapper()} method.

+ * {@link #updateHierarchicalWrapper()} method. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -75,12 +80,14 @@ public class ContainerHierarchicalWrapper /** Is the wrapped container hierarchical by itself ? */ private boolean hierarchical; - /** Constructs a new hierarchical wrapper for an existing Container. + /** + * Constructs a new hierarchical wrapper for an existing Container. * Works even if the to-be-wrapped container already implements the - * Container.Hierarchical interface. + * Container.Hierarchical interface. * * @param toBeWrapped the container that needs to be accessed * hierarchically + * @see #updateHierarchicalWrapper() */ public ContainerHierarchicalWrapper(Container toBeWrapped) { @@ -102,7 +109,8 @@ public class ContainerHierarchicalWrapper updateHierarchicalWrapper(); } - /** Updates the wrapper's internal hierarchy data to include all Items + /** + * Updates the wrapper's internal hierarchy data to include all Items * in the underlying container. If the contents of the wrapped container * change without the wrapper's knowledge, this method needs to be * called to update the hierarchy information of the Items. @@ -151,11 +159,14 @@ public class ContainerHierarchicalWrapper } } - /** Removes the specified Item from the wrapper's internal hierarchy - * structure. Note that the Item is not removed from the underlying + /** + * Removes the specified Item from the wrapper's internal hierarchy + * structure. + *

+ * Note : The Item is not removed from the underlying * Container. - * - * @param itemId ID of the item to remove from the hierarchy + *

+ * @param itemId the ID of the item to remove from the hierarchy. */ private void removeFromHierarchyWrapper(Object itemId) { @@ -172,11 +183,12 @@ public class ContainerHierarchicalWrapper noChildrenAllowed.remove(itemId); } - /** Adds the specified Item specified to the internal hierarchy + /** + * Adds the specified Item specified to the internal hierarchy * structure. The new item is added as a root Item. The underlying * container is not modified. * - * @param itemId ID of the item to add to the hierarchy + * @param itemId the ID of the item to add to the hierarchy. */ private void addToHierarchyWrapper(Object itemId) { roots.add(itemId); @@ -195,7 +207,7 @@ public class ContainerHierarchicalWrapper return !noChildrenAllowed.contains(itemId); } - /* Get the IDs of the children of the specified Item. + /* Gets the IDs of the children of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -211,7 +223,7 @@ public class ContainerHierarchicalWrapper return Collections.unmodifiableCollection(c); } - /* Get the ID of the parent of the specified Item. + /* Gets the ID of the parent of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -250,7 +262,7 @@ public class ContainerHierarchicalWrapper return parent.get(itemId) == null; } - /* Get the IDs of the root elements in the container. + /* Gets the IDs of the root elements in the container. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -263,17 +275,20 @@ public class ContainerHierarchicalWrapper return Collections.unmodifiableCollection(roots); } - /**

Sets the given Item's capability to have children. If the Item - * identified with itemId already has children and - * areChildrenAllowed is false this method fails and + /** + *

+ * Sets the given Item's capability to have children. If the Item + * identified with the itemId already has children and the + * areChildrenAllowed is false this method fails and * false is returned; the children must be first explicitly * removed with {@link #setParent(Object itemId, Object newParentId)} or - * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}.

+ * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}. + *

* - * @param itemId ID of the Item in the container whose child - * capability is to be set - * @param childrenAllowed boolean value specifying if the Item - * can have children or not + * @param itemId the ID of the Item in the container whose child + * capability is to be set. + * @param childrenAllowed the boolean value specifying if the Item + * can have children or not. * @return true if the operation succeeded, * false if not */ @@ -298,16 +313,19 @@ public class ContainerHierarchicalWrapper return true; } - /**

Sets the parent of an Item. The new parent item must exist and be + /** + *

+ * Sets the parent of an Item. The new parent item must exist and be * able to have children. * (canHaveChildren(newParentId) == true). It is also * possible to detach a node from the hierarchy (and thus make it root) - * by setting the parent null.

+ * by setting the parent null. + *

* - * @param itemId ID of the item to be set as the child of the Item - * identified with newParentId - * @param newParentId ID of the Item that's to be the new parent - * of the Item identified with itemId + * @param itemId the ID of the item to be set as the child of the Item + * identified with newParentId. + * @param newParentId the ID of the Item that's to be the new parent + * of the Item identified with itemId. * @return true if the operation succeeded, * false if not */ @@ -388,11 +406,14 @@ public class ContainerHierarchicalWrapper return true; } - /** Creates a new Item into the Container, assigns it an + /** + * Creates a new Item into the Container, assigns it an * automatic ID, and adds it to the hierarchy. * * @return the autogenerated ID of the new Item or null * if the operation failed + * @throws UnsupportedOperationException + * if the addItem is not supported. */ public Object addItem() throws UnsupportedOperationException { @@ -402,10 +423,14 @@ public class ContainerHierarchicalWrapper return id; } - /** Adds a new Item by its ID to the underlying container and to the + /** + * Adds a new Item by its ID to the underlying container and to the * hierarchy. - * - * @return the added Item or null if the operation failed + * @param itemId + * the ID of the Item to be created. + * @return the added Item or null if the operation failed. + * @throws UnsupportedOperationException + * if the addItem is not supported. */ public Item addItem(Object itemId) throws UnsupportedOperationException { @@ -415,11 +440,14 @@ public class ContainerHierarchicalWrapper return item; } - /** Removes all items from the underlying container and from the + /** + * Removes all items from the underlying container and from the * hierarcy. * * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the removeAllItems is not supported. */ public boolean removeAllItems() throws UnsupportedOperationException { @@ -434,11 +462,15 @@ public class ContainerHierarchicalWrapper return success; } - /** Removes an Item specified by itemId from the underlying + /** + * Removes an Item specified by the itemId from the underlying * container and from the hierarcy. - * + * @param itemId + * the ID of the Item to be removed. * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the removeItem is not supported. */ public boolean removeItem(Object itemId) throws UnsupportedOperationException { @@ -451,14 +483,17 @@ public class ContainerHierarchicalWrapper return success; } - /** Adds a new Property to all Items in the Container. + /** + * Adds a new Property to all Items in the Container. * - * @param propertyId ID of the new Property - * @param type Data type of the new Property - * @param defaultValue The value all created Properties are - * initialized to + * @param propertyId the ID of the new Property. + * @param type the Data type of the new Property. + * @param defaultValue the value all created Properties are + * initialized to. * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the addContainerProperty is not supported. */ public boolean addContainerProperty( Object propertyId, @@ -469,13 +504,18 @@ public class ContainerHierarchicalWrapper return container.addContainerProperty(propertyId, type, defaultValue); } - /** Removes the specified Property from the underlying container and - * from the hierarchy. Note that the Property will be removed from all + /** + * Removes the specified Property from the underlying container and + * from the hierarchy. + *

+ * Note : The Property will be removed from all * Items in the Container. - * - * @param propertyId ID of the Property to remove + *

+ * @param propertyId the ID of the Property to remove. * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the removeContainerProperty is not supported. */ public boolean removeContainerProperty(Object propertyId) throws UnsupportedOperationException { diff --git a/src/com/itmill/toolkit/data/util/ContainerOrderedWrapper.java b/src/com/itmill/toolkit/data/util/ContainerOrderedWrapper.java index 51e5bc4e20..da54d2b2c8 100644 --- a/src/com/itmill/toolkit/data/util/ContainerOrderedWrapper.java +++ b/src/com/itmill/toolkit/data/util/ContainerOrderedWrapper.java @@ -37,13 +37,18 @@ import com.itmill.toolkit.data.Container; import com.itmill.toolkit.data.Item; import com.itmill.toolkit.data.Property; -/**

A wrapper class for adding external ordering to containers not +/** + *

+ * A wrapper class for adding external ordering to containers not * implementing the {@link com.itmill.toolkit.data.Container.Ordered} - * interface.

+ * interface. + *

* - *

If the wrapped container is changed directly (that is, not through + *

+ * If the wrapped container is changed directly (that is, not through * the wrapper), the ordering must be updated with the - * {@link #updateOrderWrapper()} method.

+ * {@link #updateOrderWrapper()} method. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -55,55 +60,67 @@ public class ContainerOrderedWrapper Container.ItemSetChangeNotifier, Container.PropertySetChangeNotifier { - /** The wrapped container */ + /** + * The wrapped container + */ private Container container; - /** Ordering information, ie. the mapping from Item ID to the next + /** + * Ordering information, ie. the mapping from Item ID to the next * item ID */ private Hashtable next; - /** Reverse ordering information for convenience and performance + /** + * Reverse ordering information for convenience and performance * reasons. */ private Hashtable prev; - /** ID of the first Item in the container. */ + /** + * ID of the first Item in the container. + */ private Object first; - /** ID of the last Item in the container. */ + /** + * ID of the last Item in the container. + */ private Object last; - /** Is the wrapped container ordered by itself, ie. does it implement + /** + * Is the wrapped container ordered by itself, ie. does it implement * the Container.Ordered interface by itself? If it does, this class * will use the methods of the underlying container directly. */ private boolean ordered = false; - /** Constructs a new ordered wrapper for an existing Container. Works + /** + * Constructs a new ordered wrapper for an existing Container. Works * even if the to-be-wrapped container already implements the * Container.Ordered interface. * - * @param toBeWrapped the container whose contents need to be ordered + * @param toBeWrapped the container whose contents need to be ordered. */ public ContainerOrderedWrapper(Container toBeWrapped) { container = toBeWrapped; ordered = container instanceof Container.Ordered; - // Check arguments + // Checks arguments if (container == null) throw new NullPointerException("Null can not be wrapped"); - // Create initial order if needed + // Creates initial order if needed updateOrderWrapper(); } - /** Removes the specified Item from the wrapper's internal hierarchy - * structure. Note that the Item is not removed from the underlying - * Container. - * - * @param id ID of the Item to be removed from the ordering + /** + * Removes the specified Item from the wrapper's internal hierarchy + * structure. + *

+ * Note : The Item is not removed from the underlying Container. + *

+ * @param id the ID of the Item to be removed from the ordering. */ private void removeFromOrderWrapper(Object id) { if (id != null) { @@ -122,14 +139,15 @@ public class ContainerOrderedWrapper } } - /** Adds the specified Item to the last position in the wrapper's + /** + * Registers the specified Item to the last position in the wrapper's * internal ordering. The underlying container is not modified. * - * @param id ID of the Item to be added to the ordering + * @param id the ID of the Item to be added to the ordering. */ private void addToOrderWrapper(Object id) { - // Add the if to tail + // Adds the if to tail if (last != null) { next.put(last, id); prev.put(id, last); @@ -139,11 +157,13 @@ public class ContainerOrderedWrapper } } - /** Adds the specified Item after the specified itemId in the wrapper's + /** + * Registers the specified Item after the specified itemId in the wrapper's * internal ordering. The underlying container is not modified. * Given item id must be in the container, or must be null. * - * @param id ID of the Item to be added to the ordering + * @param id the ID of the Item to be added to the ordering. + * @param previousItemId the Id of the previous item. */ private void addToOrderWrapper(Object id, Object previousItemId) { @@ -163,10 +183,14 @@ public class ContainerOrderedWrapper } } - /** Updates the wrapper's internal ordering information to include all - * Items in the underlying container. If the contents of the wrapped - * container change without the wrapper's knowledge, this method needs - * to be called to update the ordering information of the Items. + /** + * Updates the wrapper's internal ordering information to include all + * Items in the underlying container. + *

+ * Note : If the contents of the wrapped container change without the + * wrapper's knowledge, this method needs to be called to update + * the ordering information of the Items. + *

*/ public void updateOrderWrapper() { @@ -174,7 +198,7 @@ public class ContainerOrderedWrapper Collection ids = container.getItemIds(); - // Recreate ordering if some parts of it are missing + // Recreates ordering if some parts of it are missing if (next == null || first == null || last == null @@ -193,7 +217,7 @@ public class ContainerOrderedWrapper removeFromOrderWrapper(id); } - // Add missing items + // Adds missing items for (Iterator i = ids.iterator(); i.hasNext();) { Object id = i.next(); if (!next.containsKey(id)) @@ -212,7 +236,7 @@ public class ContainerOrderedWrapper return first; } - /* Test if the given item is the first item in the container + /* Tests if the given item is the first item in the container * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -222,7 +246,7 @@ public class ContainerOrderedWrapper return first != null && first.equals(itemId); } - /* Test if the given item is the last item in the container + /* Tests if the given item is the last item in the container * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -242,7 +266,7 @@ public class ContainerOrderedWrapper return last; } - /* Get the item that is next from the specified item. + /* Gets the item that is next from the specified item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -252,7 +276,7 @@ public class ContainerOrderedWrapper return next.get(itemId); } - /* Get the item that is previous from the specified item. + /* Gets the item that is previous from the specified item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -262,12 +286,13 @@ public class ContainerOrderedWrapper return prev.get(itemId); } - /** Adds a new Property to all Items in the Container. + /** + * Registers a new Property to all Items in the Container. * - * @param propertyId ID of the new Property - * @param type Data type of the new Property - * @param defaultValue The value all created Properties are - * initialized to + * @param propertyId the ID of the new Property. + * @param type the Data type of the new Property. + * @param defaultValue the value all created Properties are + * initialized to. * @return true if the operation succeeded, * false if not */ @@ -280,11 +305,14 @@ public class ContainerOrderedWrapper return container.addContainerProperty(propertyId, type, defaultValue); } - /** Creates a new Item into the Container, assigns it an + /** + * Creates a new Item into the Container, assigns it an * automatic ID, and adds it to the ordering. * * @return the autogenerated ID of the new Item or null * if the operation failed + * @throws UnsupportedOperationException + * if the addItem is not supported. */ public Object addItem() throws UnsupportedOperationException { @@ -294,10 +322,14 @@ public class ContainerOrderedWrapper return id; } - /** Adds a new Item by its ID to the underlying container and to the + /** + * Registers a new Item by its ID to the underlying container and to the * ordering. - * + * @param itemId + * the ID of the Item to be created. * @return the added Item or null if the operation failed + * @throws UnsupportedOperationException + * if the addItem is not supported. */ public Item addItem(Object itemId) throws UnsupportedOperationException { Item item = container.addItem(itemId); @@ -306,11 +338,14 @@ public class ContainerOrderedWrapper return item; } - /** Removes all items from the underlying container and from the + /** + * Removes all items from the underlying container and from the * ordering. * - * @return true if the operation succeeded, - * false if not + * @return true if the operation succeeded, otherwise + * false + * @throws UnsupportedOperationException + * if the removeAllItems is not supported. */ public boolean removeAllItems() throws UnsupportedOperationException { boolean success = container.removeAllItems(); @@ -322,11 +357,15 @@ public class ContainerOrderedWrapper return success; } - /** Removes an Item specified by itemId from the underlying + /** + * Removes an Item specified by the itemId from the underlying * container and from the ordering. - * + * @param itemId + * the ID of the Item to be removed. * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the removeItem is not supported. */ public boolean removeItem(Object itemId) throws UnsupportedOperationException { @@ -337,13 +376,17 @@ public class ContainerOrderedWrapper return success; } - /** Removes the specified Property from the underlying container and - * from the ordering. Note that the Property will be removed from all - * Items in the Container. - * - * @param propertyId ID of the Property to remove + /** + * Removes the specified Property from the underlying container and + * from the ordering. + *

+ * Note : The Property will be removed from all the Items in the Container. + *

+ * @param propertyId the ID of the Property to remove. * @return true if the operation succeeded, * false if not + * @throws UnsupportedOperationException + * if the removeContainerProperty is not supported. */ public boolean removeContainerProperty(Object propertyId) throws UnsupportedOperationException { @@ -456,10 +499,10 @@ public class ContainerOrderedWrapper if (previousItemId != null && !containsId(previousItemId)) return null; - // Add the item to container + // Adds the item to container Item item = container.addItem(newItemId); - // Put the new item to its correct place + // Puts the new item to its correct place if (item != null) addToOrderWrapper(newItemId, previousItemId); @@ -476,10 +519,10 @@ public class ContainerOrderedWrapper if (previousItemId != null && !containsId(previousItemId)) return null; - // Add the item to container + // Adds the item to container Object id = container.addItem(); - // Put the new item to its correct place + // Puts the new item to its correct place if (id != null) addToOrderWrapper(id, previousItemId); diff --git a/src/com/itmill/toolkit/data/util/FilesystemContainer.java b/src/com/itmill/toolkit/data/util/FilesystemContainer.java index 41eee1fe84..7658d2f1d7 100644 --- a/src/com/itmill/toolkit/data/util/FilesystemContainer.java +++ b/src/com/itmill/toolkit/data/util/FilesystemContainer.java @@ -47,7 +47,8 @@ import com.itmill.toolkit.data.Property; import com.itmill.toolkit.service.FileTypeResolver; import com.itmill.toolkit.terminal.Resource; -/** A hierarchical container wrapper for a filesystem. +/** + * A hierarchical container wrapper for a filesystem. * * @author IT Mill Ltd. * @version @VERSION@ @@ -55,19 +56,29 @@ import com.itmill.toolkit.terminal.Resource; */ public class FilesystemContainer implements Container.Hierarchical { - /** String identifier of a file's "name" property. */ + /** + * String identifier of a file's "name" property. + */ public static String PROPERTY_NAME = "Name"; - /** String identifier of a file's "size" property. */ + /** + * String identifier of a file's "size" property. + */ public static String PROPERTY_SIZE = "Size"; - /** String identifier of a file's "icon" property. */ + /** + * String identifier of a file's "icon" property. + */ public static String PROPERTY_ICON = "Icon"; - /** String identifier of a file's "last modified" property. */ + /** + * String identifier of a file's "last modified" property. + */ public static String PROPERTY_LASTMODIFIED = "Last Modified"; - /** List of the string identifiers for the available properties */ + /** + * List of the string identifiers for the available properties. + */ public static Collection FILE_PROPERTIES; private static Method FILEITEM_LASTMODIFIED; @@ -104,10 +115,11 @@ public class FilesystemContainer implements Container.Hierarchical { private FilenameFilter filter = null; private boolean recursive = true; - /** Construct a new FileSystemContainer with the specified + /** + * Constructs a new FileSystemContainer with the specified * file as the root of the filesystem. The files are included recursively. * - * @param root root file for the new file-system container. Null values are ignored. + * @param root the root file for the new file-system container. Null values are ignored. */ public FilesystemContainer(File root) { if (root != null) { @@ -115,10 +127,11 @@ public class FilesystemContainer implements Container.Hierarchical { } } - /** Construct a new FileSystemContainer with the specified + /** + * Constructs a new FileSystemContainer with the specified * file as the root of the filesystem. The files are included recursively. * - * @param root root file for the new file-system container + * @param root the root file for the new file-system container. * @param recursive should the container recursively contain subdirectories. */ public FilesystemContainer(File root, boolean recursive) { @@ -126,11 +139,12 @@ public class FilesystemContainer implements Container.Hierarchical { this.setRecursive(recursive); } - /** Construct a new FileSystemContainer with the specified + /** + * Constructs a new FileSystemContainer with the specified * file as the root of the filesystem. * - * @param root root file for the new file-system container - * @param extension Filename extension (w/o separator) to limit the files in container. + * @param root the root file for the new file-system container. + * @param extension the Filename extension (w/o separator) to limit the files in container. * @param recursive should the container recursively contain subdirectories. */ public FilesystemContainer( @@ -142,11 +156,12 @@ public class FilesystemContainer implements Container.Hierarchical { this.setRecursive(recursive); } - /** Construct a new FileSystemContainer with the specified + /** + * Constructs a new FileSystemContainer with the specified * root and recursivity status. * - * @param root root file for the new file-system container - * @param filter Filename filter to limit the files in container. + * @param root the root file for the new file-system container. + * @param filter the Filename filter to limit the files in container. * @param recursive should the container recursively contain subdirectories. */ public FilesystemContainer( @@ -158,9 +173,10 @@ public class FilesystemContainer implements Container.Hierarchical { this.setRecursive(recursive); } - /** Add new root file directory. - * Adds a file to be included as root file directory in the FilesystemContainer. - * @param root File to be added as root directory. Null values are ignored. + /** + * Adds new root file directory. + * Adds a file to be included as root file directory in the FilesystemContainer. + * @param root the File to be added as root directory. Null values are ignored. */ public void addRoot(File root) { if (root != null) { @@ -173,11 +189,12 @@ public class FilesystemContainer implements Container.Hierarchical { } } - /** Tests if the specified Item in the container may have children. + /** + * Tests if the specified Item in the container may have children. * Since a FileSystemContainer contains files and * directories, this method returns true for directory * Items only. - * + * @param itemId the id of the item. * @return true if the specified Item is a directory, * false otherwise. */ @@ -187,7 +204,7 @@ public class FilesystemContainer implements Container.Hierarchical { && ((File) itemId).isDirectory(); } - /* Get the ID's of all Items who are children of the specified Item. + /* Gets the ID's of all Items who are children of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -210,7 +227,7 @@ public class FilesystemContainer implements Container.Hierarchical { return Collections.unmodifiableCollection(l); } - /* Get the parent item of the specified Item. + /* Gets the parent item of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -221,7 +238,7 @@ public class FilesystemContainer implements Container.Hierarchical { return ((File) itemId).getParentFile(); } - /* Test if the specified Item has any children. + /* Tests if the specified Item has any children. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -237,7 +254,7 @@ public class FilesystemContainer implements Container.Hierarchical { return (l != null) && (l.length > 0); } - /* Test if the specified Item is the root of the filesystem. + /* Tests if the specified Item is the root of the filesystem. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -252,7 +269,7 @@ public class FilesystemContainer implements Container.Hierarchical { return false; } - /* Get the ID's of all root Items in the container. + /* Gets the ID's of all root Items in the container. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -279,10 +296,17 @@ public class FilesystemContainer implements Container.Hierarchical { return Collections.unmodifiableCollection(l); } - /** Return false - conversion from files to directories is not + /** + * Returns false when conversion from files to directories is not * supported. - * - * @return false + * @param itemId + * the ID of the item. + * @param areChildrenAllowed + * the boolean value specifying if the Item can have children or not. + * @return true if the operaton is successful otherwise + * false. + * @throws UnsupportedOperationException + * if the setChildrenAllowed is not supported. */ public boolean setChildrenAllowed( Object itemId, @@ -292,10 +316,16 @@ public class FilesystemContainer implements Container.Hierarchical { throw new UnsupportedOperationException("Conversion file to/from directory is not supported"); } - /** Return false - moving files around in the filesystem is not + /** + * Returns false when moving files around in the filesystem is not * supported. - * - * @return false + * @param itemId the ID of the item. + * @param newParentId the ID of the Item that's to be the new parent + * of the Item identified with itemId. + * @return true if the operation is successful otherwise + * false. + * @throws UnsupportedOperationException + * if the setParent is not supported. */ public boolean setParent(Object itemId, Object newParentId) throws UnsupportedOperationException { @@ -303,7 +333,7 @@ public class FilesystemContainer implements Container.Hierarchical { throw new UnsupportedOperationException("File moving is not supported"); } - /* Test if the filesystem contains the specified Item. + /* Tests if the filesystem contains the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -343,7 +373,8 @@ public class FilesystemContainer implements Container.Hierarchical { return new FileItem((File) itemId); } - /** Internal recursive method to add the files under the specified + /** + * Internal recursive method to add the files under the specified * directory to the collection. * * @param col the collection where the found items are added @@ -402,13 +433,14 @@ public class FilesystemContainer implements Container.Hierarchical { } - /** Gets the specified property of the specified file Item. The + /** + * Gets the specified property of the specified file Item. The * available file properties are "Name", "Size" and "Last Modified". - * If propertyId is not one of those, null is + * If propertyId is not one of those, null is * returned. * - * @param itemId ID of the file whose property is requested - * @param propertyId The property's ID + * @param itemId the ID of the file whose property is requested. + * @param propertyId the property's ID. * @return the requested property's value, or null */ public Property getContainerProperty(Object itemId, Object propertyId) { @@ -447,7 +479,8 @@ public class FilesystemContainer implements Container.Hierarchical { return null; } - /** Gets the collection of available file properties. + /** + * Gets the collection of available file properties. * * @return Unmodifiable collection containing all available file * properties. @@ -456,12 +489,13 @@ public class FilesystemContainer implements Container.Hierarchical { return FILE_PROPERTIES; } - /** Gets the specified property's data type. "Name" is a + /** + * Gets the specified property's data type. "Name" is a * String, "Size" is a Long, "Last Modified" - * is a Date. If propertyId is not one of + * is a Date. If propertyId is not one of * those, null is returned. * - * @param propertyId ID of the property whose type is requested. + * @param propertyId the ID of the property whose type is requested. * @return data type of the requested property, or null */ public Class getType(Object propertyId) { @@ -477,7 +511,8 @@ public class FilesystemContainer implements Container.Hierarchical { return null; } - /** Internal method to recursively calculate the number of files under + /** + * Internal method to recursively calculate the number of files under * a root directory. * * @param f the root to start counting from. @@ -499,7 +534,8 @@ public class FilesystemContainer implements Container.Hierarchical { return ret; } - /** Gets the number of Items in the container. In effect, this is the + /** + * Gets the number of Items in the container. In effect, this is the * combined amount of files and directories. * * @return Number of Items in the container. @@ -529,22 +565,27 @@ public class FilesystemContainer implements Container.Hierarchical { } } - /** A Item wrapper for files in a filesystem. + /** + * A Item wrapper for files in a filesystem. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 */ public class FileItem implements Item { - /** The wrapped file. */ + /** + * The wrapped file. + */ private File file; - /** Construct a FileItem from a existing file. */ + /** + * Constructs a FileItem from a existing file. + */ private FileItem(File file) { this.file = file; } - /* Get the specified property of this file. + /* Gets the specified property of this file. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -552,7 +593,7 @@ public class FilesystemContainer implements Container.Hierarchical { return FilesystemContainer.this.getContainerProperty(file, id); } - /* Get the IDs of all properties available for this item + /* Gets the IDs of all properties available for this item * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -560,7 +601,8 @@ public class FilesystemContainer implements Container.Hierarchical { return FilesystemContainer.this.getContainerPropertyIds(); } - /* Calculates a integer hash-code for the Property that's unique + /** + * Calculates a integer hash-code for the Property that's unique * inside the Item containing the Property. Two different Properties * inside the same Item contained in the same list always have * different hash-codes, though Properties in different Items may @@ -572,10 +614,11 @@ public class FilesystemContainer implements Container.Hierarchical { return file.hashCode() ^ FilesystemContainer.this.hashCode(); } - /* Tests if the given object is the same as the this object. + /** + * Tests if the given object is the same as the this object. * Two Properties got from an Item with the same ID are equal. * - * @param obj an object to compare with this object + * @param obj an object to compare with this object. * @return true if the given object is the same as * this object, false if not */ @@ -585,23 +628,37 @@ public class FilesystemContainer implements Container.Hierarchical { FileItem fi = (FileItem) obj; return fi.getHost() == getHost() && fi.file.equals(file); } - + /** + * Gets the host of this file. + */ private FilesystemContainer getHost() { return FilesystemContainer.this; } - + /** + * Gets the last modified date of this file. + * @return Date + */ public Date lastModified() { return new Date(this.file.lastModified()); } - + /** + * Gets the name of this file. + * @return file name of this file. + */ public String getName() { return this.file.getName(); } - + /** + * Gets the icon of this file. + * @return the icon of this file. + */ public Resource getIcon() { return FileTypeResolver.getIcon(this.file); } - + /** + * Gets the size of this file. + * @return size + */ public long getSize() { if (this.file.isDirectory()) return 0; @@ -617,7 +674,8 @@ public class FilesystemContainer implements Container.Hierarchical { return file.getName(); } - /** Filesystem container does not support adding new properties. + /** + * Filesystem container does not support adding new properties. * @see com.itmill.toolkit.data.Item#addItemProperty(Object, Property) */ public boolean addItemProperty(Object id, Property property) @@ -627,7 +685,8 @@ public class FilesystemContainer implements Container.Hierarchical { + "does not support adding new properties"); } - /** Filesystem container does not support removing properties. + /** + * Filesystem container does not support removing properties. * @see com.itmill.toolkit.data.Item#removeItemProperty(Object) */ public boolean removeItemProperty(Object id) @@ -637,7 +696,8 @@ public class FilesystemContainer implements Container.Hierarchical { } - /** Generic file extension filter for displaying only files having certain extension. + /** + * Generic file extension filter for displaying only files having certain extension. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 @@ -646,14 +706,16 @@ public class FilesystemContainer implements Container.Hierarchical { private String filter; - /** Construct new FileExtensionFilter using given extension. - * @param fileExtension File extension without the separator (dot). - * */ + /** + * Constructs new FileExtensionFilter using given extension. + * @param fileExtension the File extension without the separator (dot). + */ public FileExtensionFilter(String fileExtension) { this.filter = "." + fileExtension; } - /** Allow only files with the extension and directories. + /** + * Allows only files with the extension and directories. * @see java.io.FilenameFilter#accept(File, String) */ public boolean accept(File dir, String name) { @@ -663,38 +725,45 @@ public class FilesystemContainer implements Container.Hierarchical { } } - /** Returns the file filter used to limit the files in this container. + /** + * Returns the file filter used to limit the files in this container. * @return Used filter instance or null if no filter is assigned. */ public FilenameFilter getFilter() { return filter; } - /** Sets the file filter used to limit the files in this container. + /** + * Sets the file filter used to limit the files in this container. * @param filter The filter to set. null disables filtering. */ public void setFilter(FilenameFilter filter) { this.filter = filter; } - /** Sets the file filter used to limit the files in this container. - * @param extension Filename extension (w/o separator) to limit the files in container. + /** + * Sets the file filter used to limit the files in this container. + * @param extension the Filename extension (w/o separator) to limit the files in container. */ public void setFilter(String extension) { this.filter = new FileExtensionFilter(extension); } - /**Is this container recursive filesystem. - * @return true if container is recursive, false otherwise. + /** + * Is this container recursive filesystem. + * @return true if container is recursive, false otherwise. */ public boolean isRecursive() { return recursive; } - /** Sets the container recursive property. - * Set this to false to limit the files directly under the root file. - * Note, that this is meaningful only if the root really is a directory. - * @param New value for recursive property. + /** + * Sets the container recursive property. + * Set this to false to limit the files directly under the root file. + *

+ * Note : This is meaningful only if the root really is a directory. + *

+ * @param recursive the New value for recursive property. */ public void setRecursive(boolean recursive) { this.recursive = recursive; diff --git a/src/com/itmill/toolkit/data/util/HierarchicalContainer.java b/src/com/itmill/toolkit/data/util/HierarchicalContainer.java index 426b8726f3..1c7a773d6d 100644 --- a/src/com/itmill/toolkit/data/util/HierarchicalContainer.java +++ b/src/com/itmill/toolkit/data/util/HierarchicalContainer.java @@ -37,7 +37,8 @@ import java.util.HashSet; import com.itmill.toolkit.data.Container; import com.itmill.toolkit.data.Item; -/** A specialized Container whose contents can be accessed like it was a +/** + * A specialized Container whose contents can be accessed like it was a * tree-like structure. * * @author IT Mill Ltd. @@ -48,16 +49,24 @@ public class HierarchicalContainer extends IndexedContainer implements Container.Hierarchical { - /** Set of IDs of those contained Items that can't have children. */ + /** + * Set of IDs of those contained Items that can't have children. + */ private HashSet noChildrenAllowed = new HashSet(); - /** Mapping from Item ID to parent Item */ + /** + * Mapping from Item ID to parent Item. + */ private Hashtable parent = new Hashtable(); - /** Mapping from Item ID to a list of child IDs */ + /** + * Mapping from Item ID to a list of child IDs. + */ private Hashtable children = new Hashtable(); - /** List that contains all root elements of the container. */ + /** + * List that contains all root elements of the container. + */ private LinkedList roots = new LinkedList(); /* Can the specified Item have any children? @@ -68,7 +77,7 @@ public class HierarchicalContainer return !noChildrenAllowed.contains(itemId); } - /* Get the IDs of the children of the specified Item. + /* Gets the IDs of the children of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -79,7 +88,7 @@ public class HierarchicalContainer return Collections.unmodifiableCollection(c); } - /* Get the ID of the parent of the specified Item. + /* Gets the ID of the parent of the specified Item. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -103,7 +112,7 @@ public class HierarchicalContainer return parent.get(itemId) == null; } - /* Get the IDs of the root elements in the container. + /* Gets the IDs of the root elements in the container. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -111,27 +120,30 @@ public class HierarchicalContainer return Collections.unmodifiableCollection(roots); } - /**

Sets the given Item's capability to have children. If the Item - * identified with itemId already has children and - * areChildrenAllowed is false this method fails and + /** + *

+ * Sets the given Item's capability to have children. If the Item + * identified with the itemId already has children and the + * areChildrenAllowed is false this method fails and * false is returned; the children must be first explicitly * removed with {@link #setParent(Object itemId, Object newParentId)} or - * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}.

+ * {@link com.itmill.toolkit.data.Container#removeItem(Object itemId)}. + *

* - * @param itemId ID of the Item in the container whose child - * capability is to be set - * @param childrenAllowed boolean value specifying if the Item - * can have children or not + * @param itemId the ID of the Item in the container whose child + * capability is to be set. + * @param childrenAllowed the boolean value specifying if the Item + * can have children or not. * @return true if the operation succeeded, * false if not */ public boolean setChildrenAllowed(Object itemId, boolean childrenAllowed) { - // Check that the item is in the container + // Checks that the item is in the container if (!containsId(itemId)) return false; - // Update status + // Updates status if (childrenAllowed) noChildrenAllowed.remove(itemId); else @@ -140,29 +152,32 @@ public class HierarchicalContainer return true; } - /**

Sets the parent of an Item. The new parent item must exist and be + /** + *

+ * Sets the parent of an Item. The new parent item must exist and be * able to have children. * (canHaveChildren(newParentId) == true). It is also * possible to detach a node from the hierarchy (and thus make it root) - * by setting the parent null.

+ * by setting the parent null. + *

* - * @param itemId ID of the item to be set as the child of the Item - * identified with newParentId - * @param newParentId ID of the Item that's to be the new parent - * of the Item identified with itemId + * @param itemId the ID of the item to be set as the child of the Item + * identified with newParentId. + * @param newParentId the ID of the Item that's to be the new parent + * of the Item identified with itemId. * @return true if the operation succeeded, * false if not */ public boolean setParent(Object itemId, Object newParentId) { - // Check that the item is in the container + // Checks that the item is in the container if (!containsId(itemId)) return false; - // Get the old parent + // Gets the old parent Object oldParentId = parent.get(itemId); - // Check if no change is necessary + // Checks if no change is necessary if ((newParentId == null && oldParentId == null) || newParentId.equals(oldParentId)) return true; @@ -170,7 +185,7 @@ public class HierarchicalContainer // Making root if (newParentId == null) { - // Remove from old parents children list + // Removes from old parents children list LinkedList l = (LinkedList) children.get(itemId); if (l != null) { l.remove(itemId); @@ -181,24 +196,24 @@ public class HierarchicalContainer // Add to be a root roots.add(itemId); - // Update parent + // Updates parent parent.remove(itemId); return true; } - // Check that the new parent exists in container and can have + // Checks that the new parent exists in container and can have // children if (!containsId(newParentId) || noChildrenAllowed.contains(newParentId)) return false; - // Check that setting parent doesn't result to a loop + // Checks that setting parent doesn't result to a loop Object o = newParentId; while (o != null && !o.equals(itemId)) o = parent.get(o); if (o != null) return false; - // Update parent + // Updates parent parent.put(itemId, newParentId); LinkedList pcl = (LinkedList) children.get(newParentId); if (pcl == null) { @@ -207,7 +222,7 @@ public class HierarchicalContainer } pcl.add(itemId); - // Remove from old parent or root + // Removes from old parent or root if (oldParentId == null) roots.remove(itemId); else { diff --git a/src/com/itmill/toolkit/data/util/IndexedContainer.java b/src/com/itmill/toolkit/data/util/IndexedContainer.java index e11b6193c1..589557a385 100644 --- a/src/com/itmill/toolkit/data/util/IndexedContainer.java +++ b/src/com/itmill/toolkit/data/util/IndexedContainer.java @@ -38,7 +38,7 @@ import com.itmill.toolkit.data.Property; /** * Indexed container implementation. *

- * A list implementation of the com.itmill.toolkit.data.Container interface. A + * A list implementation of the com.itmill.toolkit.data.Container interface. A * list is a ordered collection wherein the user has a precise control over * where in the list each new Item is inserted. The user may access the Items by * their integer index (position in the list) or by their Item ID. @@ -58,13 +58,19 @@ public class IndexedContainer implements Container, Container.Indexed, /* Internal structure *************************************************** */ - /** Linked list of ordered Item IDs */ + /** + * Linked list of ordered Item IDs. + */ private ArrayList itemIds = new ArrayList(); - /** Linked list of ordered Property IDs */ + /** + * Linked list of ordered Property IDs. + */ private ArrayList propertyIds = new ArrayList(); - /** Property ID to type mapping */ + /** + * Property ID to type mapping. + */ private Hashtable types = new Hashtable(); /** @@ -80,7 +86,7 @@ public class IndexedContainer implements Container, Container.Indexed, /** * List of all Property value change event listeners listening all the - * properties + * properties. */ private LinkedList propertyValueChangeListeners = null; @@ -92,16 +98,24 @@ public class IndexedContainer implements Container, Container.Indexed, */ private Hashtable singlePropertyValueChangeListeners = null; - /** List of all Property set change event listeners */ + /** + * List of all Property set change event listeners. + */ private LinkedList propertySetChangeListeners = null; - /** List of all container Item set change event listeners */ + /** + * List of all container Item set change event listeners. + */ private LinkedList itemSetChangeListeners = null; - /** Temporary store for sorting property ids */ + /** + * Temporary store for sorting property ids. + */ private Object[] sortPropertyId; - /** Temporary store for sorting direction */ + /** + * Temporary store for sorting direction. + */ private boolean[] sortDirection; /* Container constructors *********************************************** */ @@ -124,7 +138,7 @@ public class IndexedContainer implements Container, Container.Indexed, * contain the requested Item, null is returned. * * @param itemId - * ID of the Item to retrieve + * the ID of the Item to retrieve. * @return the Item with the given ID or null if the Item is * not found in the list */ @@ -158,7 +172,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Gets the type of a Property stored in the list. * * @param id - * ID of the Property + * the ID of the Property. * @return Type of the requested Property */ public Class getType(Object propertyId) { @@ -171,9 +185,9 @@ public class IndexedContainer implements Container, Container.Indexed, * is returned. * * @param itemId - * ID of the Item which contains the requested Property + * the ID of the Item which contains the requested Property. * @param propertyId - * ID of the Property to retrieve + * the ID of the Property to retrieve. * @return Property with the given ID or null * * @see com.itmill.toolkit.data.Container#getContainerProperty(Object, @@ -198,7 +212,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Tests if the list contains the specified Item * * @param itemId - * ID the of Item to be tested for + * the ID the of Item to be tested for. * @return true if the operation succeeded, * false if not */ @@ -207,15 +221,15 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Add a new Property to all Items in the list. The Property ID, data type + * Adds a new Property to all Items in the list. The Property ID, data type * and default value of the new Property are given as parameters. * * @param propertyId - * ID of the new Property + * the ID of the new Property. * @param type - * Data type of the new Property + * the Data type of the new Property. * @param defaultValue - * The value all created Properties are initialized to + * the value all created Properties are initialized to. * @return true if the operation succeeded, * false if not */ @@ -230,7 +244,7 @@ public class IndexedContainer implements Container, Container.Indexed, if (propertyIds.contains(propertyId)) return false; - // Add the Property to Property list and types + // Adds the Property to Property list and types propertyIds.add(propertyId); types.put(propertyId, type); @@ -240,33 +254,34 @@ public class IndexedContainer implements Container, Container.Indexed, getItem(i.next()).getItemProperty(propertyId).setValue( defaultValue); - // Send a change event + // Sends a change event fireContainerPropertySetChange(); return true; } /** - * Remove all Items from the list. Note that Property ID and type - * information is preserved. - * + * Removes all Items from the list. + *

+ * Note : The Property ID and type information is preserved. + *

* @return true if the operation succeeded, * false if not */ public boolean removeAllItems() { - // Remove all Items + // Removes all Items itemIds.clear(); items.clear(); - // Send a change event + // Sends a change event fireContentsChange(); return true; } /** - * Create a new Item into the list, and assign it an automatic ID. The new + * Creates a new Item into the list, and assign it an automatic ID. The new * ID is returned, or null if the operation fails. After a * successful call you can use the * {@link #getItem(Object ItemId) getItem}method to fetch the @@ -277,46 +292,46 @@ public class IndexedContainer implements Container, Container.Indexed, */ public Object addItem() { - // Create a new id + // Creates a new id Object id = new Object(); - // Add the Item into container + // Adds the Item into container addItem(id); return id; } /** - * Create a new Item with the given ID into the list. The new Item is + * Creates a new Item with the given ID into the list. The new Item is * returned, and it is ready to have its Properties modified. Returns * null if the operation fails or the Container already * contains a Item with the given ID. * * @param itemId - * ID of the Item to be created + * the ID of the Item to be created. * @return Created new Item, or null in case of a failure */ public Item addItem(Object itemId) { - // Make sure that the Item has not been created yet + // Makes sure that the Item has not been created yet if (items.containsKey(itemId)) return null; - // Add the Item to container + // Adds the Item to container itemIds.add(itemId); items.put(itemId, new Hashtable()); - // Send the event + // Sends the event fireContentsChange(); return getItem(itemId); } /** - * Remove the Item corresponding to the given Item ID from the list. + * Removes the Item corresponding to the given Item ID from the list. * * @param itemId - * ID of the Item to remove + * the ID of the Item to remove. * @return true if the operation succeeded, * false if not */ @@ -332,11 +347,11 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Remove a Property specified by the given Property ID from the list. Note + * Removes a Property specified by the given Property ID from the list. Note * that the Property will be removed from all Items in the list. * * @param propertyId - * ID of the Property to remove + * the ID of the Property to remove. * @return true if the operation succeeded, * false if not */ @@ -346,7 +361,7 @@ public class IndexedContainer implements Container, Container.Indexed, if (!propertyIds.contains(propertyId)) return false; - // Remove the Property to Property list and types + // Removes the Property to Property list and types propertyIds.remove(propertyId); types.remove(propertyId); @@ -354,7 +369,7 @@ public class IndexedContainer implements Container, Container.Indexed, for (Iterator i = itemIds.iterator(); i.hasNext();) ((Hashtable) items.get(i.next())).remove(propertyId); - // Send a change event + // Sends a change event fireContainerPropertySetChange(); return true; @@ -390,11 +405,11 @@ public class IndexedContainer implements Container, Container.Indexed, /** * Gets the ID of the Item following the Item that corresponds to - * itemId. If the given Item is the last or not found in the + * the itemId. If the given Item is the last or not found in the * list, null is returned. * * @param itemId - * ID of an Item in the list + * the ID of an Item in the list. * @return ID of the next Item or null */ public Object nextItemId(Object itemId) { @@ -407,11 +422,11 @@ public class IndexedContainer implements Container, Container.Indexed, /** * Gets the ID of the Item preceding the Item that corresponds to - * itemId. If the given Item is the first or not found in + * the itemId. If the given Item is the first or not found in * the list, null is returned. * * @param itemId - * ID of an Item in the list + * the ID of an Item in the list. * @return ID of the previous Item or null */ public Object prevItemId(Object itemId) { @@ -427,7 +442,7 @@ public class IndexedContainer implements Container, Container.Indexed, * the list. * * @param itemId - * ID of an Item in the list + * the ID of an Item in the list. * @return true if the Item is first in the list, * false if not */ @@ -440,7 +455,7 @@ public class IndexedContainer implements Container, Container.Indexed, * the list. * * @param itemId - * ID of an Item in the list + * the ID of an Item in the list. * @return true if the Item is last in the list, * false if not */ @@ -483,7 +498,7 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Get ID with the index. The following is true for the index: 0 <= index < + * Gets ID with the index. The following is true for the index: 0 <= index < * size(). * * @return ID in the given index. @@ -495,7 +510,7 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Get the index of an id. The following is true for the index: 0 <= index < + * Gets the index of an id. The following is true for the index: 0 <= index < * size(). * * @return Index of the Item or -1 if the Item is not in the container. @@ -515,11 +530,11 @@ public class IndexedContainer implements Container, Container.Indexed, if (items.containsKey(newItemId)) return null; - // Add the Item to container + // Adds the Item to container itemIds.add(index, newItemId); items.put(newItemId, new Hashtable()); - // Send the event + // Sends the event fireContentsChange(); return getItem(newItemId); @@ -530,10 +545,10 @@ public class IndexedContainer implements Container, Container.Indexed, */ public Object addItemAt(int index) { - // Create a new id + // Creates a new id Object id = new Object(); - // Add the Item into container + // Adds the Item into container addItemAt(index, id); return id; @@ -640,7 +655,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Registers a new Property set change listener for this list. * * @param listener - * the new Listener to be registered + * the new Listener to be registered. */ public void addListener(Container.PropertySetChangeListener listener) { if (propertySetChangeListeners == null) @@ -652,7 +667,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Removes a previously registered Property set change listener. * * @param listener - * listener to be removed + * the listener to be removed. */ public void removeListener(Container.PropertySetChangeListener listener) { if (propertySetChangeListeners != null) @@ -663,7 +678,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Adds a Item set change listener for the list. * * @param listener - * listener to be added + * the listener to be added. */ public void addListener(Container.ItemSetChangeListener listener) { if (itemSetChangeListeners == null) @@ -675,7 +690,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Removes a Item set change listener from the object. * * @param listener - * listener to be removed + * the listener to be removed. */ public void removeListener(Container.ItemSetChangeListener listener) { if (itemSetChangeListeners != null) @@ -698,17 +713,20 @@ public class IndexedContainer implements Container, Container.Indexed, * Removes a previously registered value change listener. * * @param listener - * listener to be removed + * the listener to be removed. */ public void removeListener(Property.ValueChangeListener listener) { if (propertyValueChangeListeners != null) propertyValueChangeListeners.remove(listener); } - /** Send a Property value change event to all interested listeners */ + /** + * Sends a Property value change event to all interested listeners. + * @param source the IndexedContainerProperty object. + */ private void firePropertyValueChange(IndexedContainerProperty source) { - // Send event to listeners listening all value changes + // Sends event to listeners listening all value changes if (propertyValueChangeListeners != null) { Object[] l = propertyValueChangeListeners.toArray(); Property.ValueChangeEvent event = new IndexedContainer.PropertyValueChangeEvent( @@ -717,7 +735,7 @@ public class IndexedContainer implements Container, Container.Indexed, ((Property.ValueChangeListener) l[i]).valueChange(event); } - // Send event to single property value change listeners + // Sends event to single property value change listeners if (singlePropertyValueChangeListeners != null) { Hashtable propertySetToListenerListMap = (Hashtable) singlePropertyValueChangeListeners .get(source.propertyId); @@ -736,7 +754,9 @@ public class IndexedContainer implements Container, Container.Indexed, } - /** Send a Property set change event to all interested listeners */ + /** + * Sends a Property set change event to all interested listeners. + */ private void fireContainerPropertySetChange() { if (propertySetChangeListeners != null) { Object[] l = propertySetChangeListeners.toArray(); @@ -748,7 +768,9 @@ public class IndexedContainer implements Container, Container.Indexed, } } - /** Send Item set change event to all registered interested listeners */ + /** + * Sends Item set change event to all registered interested listeners. + */ private void fireContentsChange() { if (itemSetChangeListeners != null) { Object[] l = itemSetChangeListeners.toArray(); @@ -760,7 +782,15 @@ public class IndexedContainer implements Container, Container.Indexed, } } - /** Add new single Property change listener */ + /** + * Adds new single Property change listener. + * @param propertyId + * the ID of the Property to add. + * @param itemId + * the ID of the Item . + * @param listener + * the listener to be added. + */ private void addSinglePropertyChangeListener(Object propertyId, Object itemId, Property.ValueChangeListener listener) { if (listener != null) { @@ -783,7 +813,15 @@ public class IndexedContainer implements Container, Container.Indexed, } } - /** Remove a previously registered single Property change listener */ + /** + * Removes a previously registered single Property change listener. + * @param propertyId + * the ID of the Property to remove. + * @param itemId + * the ID of the Item. + * @param listener + * the listener to be removed. + */ private void removeSinglePropertyChangeListener(Object propertyId, Object itemId, Property.ValueChangeListener listener) { if (listener != null && singlePropertyValueChangeListeners != null) { @@ -816,21 +854,21 @@ public class IndexedContainer implements Container, Container.Indexed, */ class IndexedContainerItem implements Item { - /** Item ID in the host container for this Item */ + /** + * Item ID in the host container for this Item. + */ private Object itemId; /** * Constructs a new ListItem instance and connects it to a host * container. * - * @param host - * the list that contains this Item * @param itemId - * Item ID of the new Item + * the Item ID of the new Item. */ private IndexedContainerItem(Object itemId) { - // Get the item contents from the host + // Gets the item contents from the host if (itemId == null) throw new NullPointerException(); this.itemId = itemId; @@ -842,7 +880,7 @@ public class IndexedContainer implements Container, Container.Indexed, * null is returned. * * @param id - * identifier of the Property to get + * the identifier of the Property to get. * @return the Property with the given ID or null */ public Property getItemProperty(Object id) { @@ -909,7 +947,10 @@ public class IndexedContainer implements Container, Container.Indexed, IndexedContainerItem li = (IndexedContainerItem) obj; return getHost() == li.getHost() && itemId.equals(li.itemId); } - + /** + * + * @return + */ private IndexedContainer getHost() { return IndexedContainer.this; } @@ -938,7 +979,7 @@ public class IndexedContainer implements Container, Container.Indexed, } - /* + /** * A class implementing the com.itmill.toolkit.data.Property interface to be * contained in the Items contained in the list. @author IT Mill Ltd. * @@ -948,10 +989,14 @@ public class IndexedContainer implements Container, Container.Indexed, private class IndexedContainerProperty implements Property, Property.ValueChangeNotifier { - /** ID of the Item, where the Property resides */ + /** + * ID of the Item, where the Property resides. + */ private Object itemId; - /** Id of the Property */ + /** + * Id of the Property. + */ private Object propertyId; /** @@ -959,12 +1004,12 @@ public class IndexedContainer implements Container, Container.Indexed, * a ListContainer. * * @param itemId - * ID of the Item to connect the new Property to + * the ID of the Item to connect the new Property to. * @param propertyId - * Property ID of the new Property + * the Property ID of the new Property. * @param host * the list that contains the Item to contain the new - * Property + * Property. */ private IndexedContainerProperty(Object itemId, Object propertyId) { if (itemId == null || propertyId == null) @@ -974,13 +1019,13 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Return the type of the Property. The methods getValue + * Returns the type of the Property. The methods getValue * and setValue must be compatible with this type: one * must be able to safely cast the value returned from * getValue to the given type and pass any variable * assignable to this type as a parameter to setValue - * Test if the Property is in read-only mode. In read-only mode calls to + * Tests if the Property is in read-only mode. In read-only mode calls to * the method setValue will throw * ReadOnlyException s and will not modify the value of * the Property. *

* * @return true if the Property is in read-only mode, - * false if it's not + * false if it's not. */ public boolean isReadOnly() { return readOnlyProperties.contains(this); } /** - * Set the Property's read-only mode to the specified status. + * Sets the Property's read-only mode to the specified status. * * @param newStatus - * new read-only status of the Property + * the new read-only status of the Property. */ public void setReadOnly(boolean newStatus) { if (newStatus) @@ -1030,7 +1075,7 @@ public class IndexedContainer implements Container, Container.Indexed, * to assign the value, * * @param newValue - * New value of the Property. This should be assignable to + * the New value of the Property. This should be assignable to * the Property's internal type or support * toString. * @@ -1044,7 +1089,7 @@ public class IndexedContainer implements Container, Container.Indexed, public void setValue(Object newValue) throws Property.ReadOnlyException, Property.ConversionException { - // Get the Property set + // Gets the Property set Hashtable propertySet = (Hashtable) items.get(itemId); // Support null values on all types @@ -1059,11 +1104,11 @@ public class IndexedContainer implements Container, Container.Indexed, else try { - // Get the string constructor + // Gets the string constructor Constructor constr = getType().getConstructor( new Class[] { String.class }); - // Create new object from the string + // Creates new object from the string propertySet.put(propertyId, constr .newInstance(new Object[] { newValue.toString() })); @@ -1078,7 +1123,7 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Return the value of the Property in human readable textual format. + * Returns the value of the Property in human readable textual format. * The return value should be assignable to the setValue * method if the Property is not in read-only mode. * @@ -1129,7 +1174,7 @@ public class IndexedContainer implements Container, Container.Indexed, * Registers a new value change listener for this Property. * * @param listener - * the new Listener to be registered + * the new Listener to be registered. * @see com.itmill.toolkit.data.Property.ValueChangeNotifier#addListener(ValueChangeListener) */ public void addListener(Property.ValueChangeListener listener) { @@ -1153,15 +1198,13 @@ public class IndexedContainer implements Container, Container.Indexed, } - /* - * (non-Javadoc) - * + /** * @see com.itmill.toolkit.data.Container.Sortable#sort(java.lang.Object[], * boolean[]) */ public synchronized void sort(Object[] propertyId, boolean[] ascending) { - // Remove any non-sortable property ids + // Removes any non-sortable property ids ArrayList ids = new ArrayList(); ArrayList orders = new ArrayList(); Collection sortable = getSortableContainerPropertyIds(); @@ -1189,9 +1232,7 @@ public class IndexedContainer implements Container, Container.Indexed, } - /* - * (non-Javadoc) - * + /** * @see com.itmill.toolkit.data.Container.Sortable#getSortableContainerPropertyIds() */ public Collection getSortableContainerPropertyIds() { @@ -1210,7 +1251,7 @@ public class IndexedContainer implements Container, Container.Indexed, } /** - * Compare two items for sorting. + * Compares two items for sorting. * * @see java.util.Comparator#compare(java.lang.Object, java.lang.Object) * @see #sort((java.lang.Object[], boolean[]) @@ -1255,10 +1296,15 @@ public class IndexedContainer implements Container, Container.Indexed, return 0; } - /* Support cloning of the IndexedContainer cleanly */ + /** + * Supports cloning of the IndexedContainer cleanly. + * @throws CloneNotSupportedException + * if an object cannot be cloned. +. + */ public Object clone() throws CloneNotSupportedException { - // Create the clone + // Creates the clone IndexedContainer nc = new IndexedContainer(); // Clone the shallow properties @@ -1304,7 +1350,10 @@ public class IndexedContainer implements Container, Container.Indexed, return nc; } - + + /** + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { // Only ones of the objects of the same class can be equal @@ -1312,7 +1361,7 @@ public class IndexedContainer implements Container, Container.Indexed, return false; IndexedContainer o = (IndexedContainer) obj; - // Check the properties one by one + // Checks the properties one by one if (itemIds != o.itemIds && o.itemIds != null && !o.itemIds.equals(this.itemIds)) return false; @@ -1356,7 +1405,10 @@ public class IndexedContainer implements Container, Container.Indexed, return true; } - + + /** + * @see java.lang.Object#hashCode() + */ public int hashCode() { // The hash-code is calculated as combination hash of the members diff --git a/src/com/itmill/toolkit/data/util/MethodProperty.java b/src/com/itmill/toolkit/data/util/MethodProperty.java index e80a27de85..d058feb029 100644 --- a/src/com/itmill/toolkit/data/util/MethodProperty.java +++ b/src/com/itmill/toolkit/data/util/MethodProperty.java @@ -35,19 +35,26 @@ import java.util.LinkedList; import com.itmill.toolkit.data.Property; -/**

Proxy class for creating Properties from pairs of getter and setter +/** + *

+ * Proxy class for creating Properties from pairs of getter and setter * methods of a Bean property. An instance of this class can be thought as * having been attached to a field of an object. Accessing the object * through the Property interface directly manipulates the underlying - * field.

+ * field. + *

* - *

It's assumed that the return value returned by the getter method + *

+ * It's assumed that the return value returned by the getter method * is assignable to the type of the property, and the setter method - * parameter is assignable to that value.

+ * parameter is assignable to that value. + *

* - *

A valid getter method must always be available, but instance of this + *

+ * A valid getter method must always be available, but instance of this * class can be constructed with a null setter method in which - * case the resulting MethodProperty is read-only.

+ * case the resulting MethodProperty is read-only. + *

* * @author IT Mill Ltd. * @version @VERSION@ @@ -55,48 +62,70 @@ import com.itmill.toolkit.data.Property; */ public class MethodProperty implements Property { - /** The object that includes the property the MethodProperty is bound to */ + /** + * The object that includes the property the MethodProperty is bound to. + */ private Object instance; - /** Argument arrays for the getter and setter methods */ + /** + * Argument arrays for the getter and setter methods. + */ private Object[] setArgs, getArgs; - /** Is the MethodProperty read-only? */ + /** + * Is the MethodProperty read-only? + */ private boolean readOnly; - /** The getter and setter methods */ + /** + * The getter and setter methods. + */ private Method setMethod, getMethod; - /** Index of the new value in the argument list for the setter method. + /** + * Index of the new value in the argument list for the setter method. * If the setter method requires several parameters, this index tells * which one is the actual value to change. */ private int setArgumentIndex; - /** Type of the property */ + /** + * Type of the property. + */ private Class type; - /** List of listeners who are interested in the read-only status changes + /** + * List of listeners who are interested in the read-only status changes * of the MethodProperty */ private LinkedList readOnlyStatusChangeListeners = null; - /**

Creates a new instance of MethodProperty from a named bean + /** + *

+ * Creates a new instance of MethodProperty from a named bean * property. This constructor takes an object and the name of a bean * property and initializes itself with the accessor methods for the - * property. The getter method of a MethodProperty instantiated + * property. + *

+ *

+ * The getter method of a MethodProperty instantiated * with this constructor will be called with no arguments, and the - * setter method with only the new value as the sole argument.

+ * setter method with only the new value as the sole argument. + *

* - *

If the setter method is unavailable, the resulting MethodProperty - * will be read-only, otherwise it will be read-write.

+ *

+ * If the setter method is unavailable, the resulting MethodProperty + * will be read-only, otherwise it will be read-write. + *

* - *

Method names are constucted from the bean property by adding + *

+ * Method names are constucted from the bean property by adding * get/is/are/set prefix and capitalising the first character in the - * name of the given bean property

+ * name of the given bean property. + *

* - * @param instance object that includes the property - * @param beanPropertyName name of the property to bind to + * @param instance the object that includes the property. + * @param beanPropertyName the name of the property to bind to. */ public MethodProperty(Object instance, String beanPropertyName) { @@ -139,7 +168,7 @@ public class MethodProperty implements Property { // In case the get method is found, resolve the type type = getMethod.getReturnType(); - // Find the set method + // Finds the set method setMethod = null; try { setMethod = @@ -149,7 +178,7 @@ public class MethodProperty implements Property { } catch (java.lang.NoSuchMethodException skipped) { } - // Get the return type from get method + // Gets the return type from get method if (type.isPrimitive()) { if (type.equals(Boolean.TYPE)) type = Boolean.class; @@ -175,19 +204,24 @@ public class MethodProperty implements Property { this.instance = instance; } - /**

Creates a new instance of MethodProperty from named getter and - * setter methods. The getter method of a MethodProperty instantiated + /** + *

+ * Creates a new instance of MethodProperty from named getter and + * setter methods. The getter method of a MethodProperty instantiated * with this constructor will be called with no arguments, and the - * setter method with only the new value as the sole argument.

+ * setter method with only the new value as the sole argument. + *

* - *

If the setter method is null, the resulting - * MethodProperty will be read-only, otherwise it will be - * read-write.

+ *

+ * If the setter method is null, the resulting + * MethodProperty will be read-only, otherwise it will be + * read-write. + *

* - * @param type type of the property - * @param instance object that includes the property - * @param getMethodName name of the getter method - * @param setMethodName name of the setter method + * @param type the type of the property. + * @param instance the object that includes the property. + * @param getMethodName the name of the getter method. + * @param setMethodName the name of the setter method. * */ public MethodProperty( @@ -199,19 +233,24 @@ public class MethodProperty implements Property { }, new Object[] { null }, 0); } - /**

Creates a new instance of MethodProperty with the getter and - * setter methods. The getter method of a MethodProperty instantiated + /** + *

+ * Creates a new instance of MethodProperty with the getter and + * setter methods. The getter method of a MethodProperty instantiated * with this constructor will be called with no arguments, and the - * setter method with only the new value as the sole argument.

+ * setter method with only the new value as the sole argument. + *

* - *

If the setter method is null, the resulting - * MethodProperty will be read-only, otherwise it will be - * read-write.

+ *

+ * If the setter method is null, the resulting + * MethodProperty will be read-only, otherwise it will be + * read-write. + *

* - * @param type type of the property - * @param instance object that includes the property - * @param getMethod the getter method - * @param setMethod the setter method + * @param type the type of the property. + * @param instance the object that includes the property. + * @param getMethod the getter method. + * @param setMethod the setter method. */ public MethodProperty( Class type, @@ -222,29 +261,34 @@ public class MethodProperty implements Property { }, new Object[] { null }, 0); } - /**

Creates a new instance of MethodProperty from named getter and + /** + *

+ * Creates a new instance of MethodProperty from named getter and * setter methods and argument lists. The getter method of a - * MethodProperty instantiated with this constructor will be called with - * getArgs as arguments. setArgs will be used + * MethodProperty instantiated with this constructor will be called with + * the getArgs as arguments. The setArgs will be used * as the arguments for the setter method, though the argument indexed - * by setArgumentIndex will be replaced with the argument - * passed to the {@link #setValue(Object newValue)} method.

+ * by the setArgumentIndex will be replaced with the argument + * passed to the {@link #setValue(Object newValue)} method. + *

* - *

For example, if the setArgs contains A, + *

+ * For example, if the setArgs contains A, * B and C, and setArgumentIndex = * 1, the call methodProperty.setValue(X) would * result in the setter method to be called with the parameter set of - * {A, X, C}

+ * {A, X, C} + *

* - * @param type type of the property - * @param instance object that includes the property - * @param getMethodName the name of the getter method - * @param setMethodName the name of the setter method - * @param getArgs fixed argument list to be passed to the getter method - * @param setArgs fixed argument list to be passed to the setter method + * @param type the type of the property. + * @param instance the object that includes the property. + * @param getMethodName the name of the getter method. + * @param setMethodName the name of the setter method. + * @param getArgs the fixed argument list to be passed to the getter method. + * @param setArgs the fixed argument list to be passed to the setter method. * @param setArgumentIndex the index of the argument in * setArgs to be replaced with newValue when - * {@link #setValue(Object newValue)} is called + * {@link #setValue(Object newValue)} is called. */ public MethodProperty( Class type, @@ -267,22 +311,22 @@ public class MethodProperty implements Property { // Find set and get -methods Method[] m = instance.getClass().getMethods(); - // Find get method + // Finds get method boolean found = false; for (int i = 0; i < m.length; i++) { - // Test the name of the get Method + // Tests the name of the get Method if (!m[i].getName().equals(getMethodName)) { // name does not match, try next method continue; } - // Test return type + // Tests return type if (!type.equals(m[i].getReturnType())) continue; - // Test the parameter types + // Tests the parameter types Class[] c = m[i].getParameterTypes(); if (c.length != getArgs.length) { @@ -318,21 +362,21 @@ public class MethodProperty implements Property { "Could not find " + getMethodName + "-method"); } - // Find set method + // Finds set method if (setMethodName != null) { - // Find setMethod + // Finds setMethod found = false; for (int i = 0; i < m.length; i++) { - // Check name + // Checks name if (!m[i].getName().equals(setMethodName)) { // name does not match, try next method continue; } - // Check parameter compatibility + // Checks parameter compatibility Class[] c = m[i].getParameterTypes(); if (c.length != setArgs.length) { @@ -373,7 +417,7 @@ public class MethodProperty implements Property { } } - // Get the return type from get method + // Gets the return type from get method if (type.isPrimitive()) { if (type.equals(Boolean.TYPE)) type = Boolean.class; @@ -398,23 +442,28 @@ public class MethodProperty implements Property { this.instance = instance; } - /**

Creates a new instance of MethodProperty from the getter and - * setter methods, and argument lists. This constructor behaves exctly - * like {@link #MethodProperty(Class type, Object instance, String + /** + *

+ * Creates a new instance of MethodProperty from the getter and + * setter methods, and argument lists. + *

+ *

+ * This constructor behaves exactly like {@link #MethodProperty(Class type, Object instance, String * getMethodName, String setMethodName, Object [] getArgs, Object [] * setArgs, int setArgumentIndex)} except that instead of names of * the getter and setter methods this constructor is given the actual - * methods themselves.

+ * methods themselves. + *

* - * @param type type of the property - * @param instance object that includes the property - * @param getMethod the getter method - * @param setMethod the setter method - * @param getArgs fixed argument list to be passed to the getter method - * @param setArgs fixed argument list to be passed to the setter method + * @param type the type of the property. + * @param instance the object that includes the property. + * @param getMethod the getter method. + * @param setMethod the setter method. + * @param getArgs the fixed argument list to be passed to the getter method. + * @param setArgs the fixed argument list to be passed to the setter method. * @param setArgumentIndex the index of the argument in * setArgs to be replaced with newValue when - * {@link #setValue(Object newValue)} is called + * {@link #setValue(Object newValue)} is called. */ public MethodProperty( Class type, @@ -433,7 +482,7 @@ public class MethodProperty implements Property { if (setMethod != null && ( setArgumentIndex < 0 || setArgumentIndex >= setArgs.length)) throw new IndexOutOfBoundsException("The setArgumentIndex must be >= 0 and < setArgs.length"); - // Get the return type from get method + // Gets the return type from get method if (type.isPrimitive()) { if (type.equals(Boolean.TYPE)) type = Boolean.class; @@ -461,7 +510,8 @@ public class MethodProperty implements Property { this.type = type; } - /** Returns the type of the Property. The methods getValue + /** + * Returns the type of the Property. The methods getValue * and setValue must be compatible with this type: one * must be able to safely cast the value returned from * getValue to the given type and pass any variable @@ -473,8 +523,9 @@ public class MethodProperty implements Property { return type; } - /** Tests if the object is in read-only mode. In read-only mode calls - * to setValue will throw ReadOnlyExceptions + /** + * Tests if the object is in read-only mode. In read-only mode calls + * to setValue will throw ReadOnlyException * and will not modify the value of the Property. * * @return true if the object is in read-only mode, @@ -484,7 +535,8 @@ public class MethodProperty implements Property { return readOnly; } - /** Gets the value stored in the Property. The value is resolved by + /** + * Gets the value stored in the Property. The value is resolved by * calling the specified getter method with the argument specified * at instantiation. * @@ -498,7 +550,8 @@ public class MethodProperty implements Property { } } - /** Returns the value of the MethodProperty in human readable textual + /** + * Returns the value of the MethodProperty in human readable textual * format. The return value should be assignable to the * setValue method if the Property is not in read-only * mode. @@ -512,13 +565,16 @@ public class MethodProperty implements Property { return value.toString(); } - /**

Sets the setter method and getter method argument lists.

+ /** + *

+ * Sets the setter method and getter method argument lists. + *

* - * @param getArgs fixed argument list to be passed to the getter method - * @param setArgs fixed argument list to be passed to the setter method + * @param getArgs the fixed argument list to be passed to the getter method. + * @param setArgs the fixed argument list to be passed to the setter method. * @param setArgumentIndex the index of the argument in * setArgs to be replaced with newValue when - * {@link #setValue(Object newValue)} is called + * {@link #setValue(Object newValue)} is called. */ public void setArguments( Object[] getArgs, @@ -533,22 +589,24 @@ public class MethodProperty implements Property { this.setArgumentIndex = setArgumentIndex; } - /** Set the value of the property. This method supports setting from + /** + * Sets the value of the property. This method supports setting from * Strings if either String is directly * assignable to property type, or the type class contains a string * constructor. * - * @param newValue New value of the property. + * @param newValue the New value of the property. * @throws Property.ReadOnlyException if the object is in - * read-only mode + * read-only mode. * @throws Property.ConversionException if * newValue can't be converted into the Property's native - * type directly or through String + * type directly or through String. + * @see #invokeSetMethod(Object) */ public void setValue(Object newValue) throws Property.ReadOnlyException, Property.ConversionException { - // Check the mode + // Checks the mode if (isReadOnly()) throw new Property.ReadOnlyException(); @@ -562,7 +620,7 @@ public class MethodProperty implements Property { Object value; try { - // Get the string constructor + // Gets the string constructor Constructor constr = getType().getConstructor(new Class[] { String.class }); @@ -572,13 +630,15 @@ public class MethodProperty implements Property { throw new Property.ConversionException(e); } - // Create new object from the string + // Creates new object from the string invokeSetMethod(value); } } - /** Internal method to actually call the setter method of the wrapped + /** + * Internal method to actually call the setter method of the wrapped * property. + * @param value */ private void invokeSetMethod(Object value) { @@ -588,7 +648,7 @@ public class MethodProperty implements Property { setMethod.invoke(instance, new Object[] { value }); else { - // Set the value to argument array + // Sets the value to argument array Object[] args = new Object[setArgs.length]; for (int i = 0; i < setArgs.length; i++) args[i] = (i == setArgumentIndex) ? value : setArgs[i]; @@ -602,10 +662,11 @@ public class MethodProperty implements Property { } } - /** Sets the Property's read-only mode to the specified status. - * - * @param newStatus new read-only status of the Property - */ + /** + * Sets the Property's read-only mode to the specified status. + * + * @param newStatus the new read-only status of the Property. + */ public void setReadOnly(boolean newStatus) { boolean prevStatus = readOnly; if (newStatus) @@ -616,7 +677,8 @@ public class MethodProperty implements Property { fireReadOnlyStatusChange(); } - /** Exception object that signals that there were + /** + * Exception object that signals that there were * problems calling or finding the specified getter or setter methods * of the property. * @author IT Mill Ltd. @@ -629,22 +691,26 @@ public class MethodProperty implements Property { * Serial generated by eclipse. */ private static final long serialVersionUID = 3690473623827855153L; - /** Cause of the method exception */ + /** + * Cause of the method exception + */ private Throwable cause; - /** Constructs a new MethodException with the + /** + * Constructs a new MethodException with the * specified detail message. * - * @param msg the detail message + * @param msg the detail message. */ public MethodException(String msg) { super(msg); } - /** Constructs a new MethodException from another + /** + * Constructs a new MethodException from another * exception. * - * @param exception cause of the exception + * @param cause the cause of the exception. */ public MethodException(Throwable cause) { this.cause = cause; @@ -656,7 +722,9 @@ public class MethodProperty implements Property { return cause; } - /** Get the method property this exception originates from */ + /** + * Gets the method property this exception originates from. + */ public MethodProperty getMethodProperty() { return MethodProperty.this; } @@ -664,7 +732,8 @@ public class MethodProperty implements Property { /* Events *************************************************************** */ - /** An Event object specifying the Property whose read-only + /** + * An Event object specifying the Property whose read-only * status has been changed. * @author IT Mill Ltd. * @version @VERSION@ @@ -679,15 +748,17 @@ public class MethodProperty implements Property { */ private static final long serialVersionUID = 3258129163305955896L; - /** Constructs a new read-only status change event for this object. + /** + * Constructs a new read-only status change event for this object. * - * @param source source object of the event + * @param source source object of the event. */ protected ReadOnlyStatusChangeEvent(MethodProperty source) { super(source); } - /** Gets the Property whose read-only state has changed. + /** + * Gets the Property whose read-only state has changed. * * @return source Property of the event. */ @@ -697,9 +768,10 @@ public class MethodProperty implements Property { } - /** Registers a new read-only status change listener for this Property. + /** + * Registers a new read-only status change listener for this Property. * - * @param listener the new Listener to be registered + * @param listener the new Listener to be registered. */ public void addListener(Property.ReadOnlyStatusChangeListener listener) { if (readOnlyStatusChangeListeners == null) @@ -707,9 +779,10 @@ public class MethodProperty implements Property { readOnlyStatusChangeListeners.add(listener); } - /** Remove a previously registered read-only status change listener. + /** + * Removes a previously registered read-only status change listener. * - * @param listener listener to be removed + * @param listener the listener to be removed. */ public void removeListener( Property.ReadOnlyStatusChangeListener listener) { @@ -717,7 +790,8 @@ public class MethodProperty implements Property { readOnlyStatusChangeListeners.remove(listener); } - /** Send a read only status change event to all registered listeners. + /** + * Sends a read only status change event to all registered listeners. */ private void fireReadOnlyStatusChange() { if (readOnlyStatusChangeListeners != null) { diff --git a/src/com/itmill/toolkit/data/util/ObjectProperty.java b/src/com/itmill/toolkit/data/util/ObjectProperty.java index c8b8abef4d..21a7669bf6 100644 --- a/src/com/itmill/toolkit/data/util/ObjectProperty.java +++ b/src/com/itmill/toolkit/data/util/ObjectProperty.java @@ -33,7 +33,8 @@ import com.itmill.toolkit.data.Property; import java.lang.reflect.Constructor; import java.util.LinkedList; -/** A simple data object containing one typed value. This class is a +/** + * A simple data object containing one typed value. This class is a * straightforward implementation of the the * {@link com.itmill.toolkit.data.Property} interface. * @@ -44,39 +45,50 @@ import java.util.LinkedList; public class ObjectProperty implements Property, Property.ValueChangeNotifier, Property.ReadOnlyStatusChangeNotifier { - /** A boolean value storing the Property's read-only status + /** + * A boolean value storing the Property's read-only status * information. */ private boolean readOnly = false; - /** The value contained by the Property. */ + /** + * The value contained by the Property. + */ private Object value; - /** Data type of the Property's value */ + /** + * Data type of the Property's value. + */ private Class type; - /** Internal list of registered value change listeners. */ + /** + * Internal list of registered value change listeners. + */ private LinkedList valueChangeListeners = null; - /** Internal list of registered read-only status change listeners. */ + /** + * Internal list of registered read-only status change listeners. + */ private LinkedList readOnlyStatusChangeListeners = null; - /** Creates a new instance of ObjectProperty with the given value. + /** + * Creates a new instance of ObjectProperty with the given value. * The type of the property is automatically initialized to be * the type of the given value. * - * @param value Initial value of the Property + * @param value the Initial value of the Property. */ public ObjectProperty(Object value) { this(value,value.getClass()); } - /** Creates a new instance of ObjectProperty with the given value and + /** + * Creates a new instance of ObjectProperty with the given value and * type. * - * @param value Initial value of the Property - * @param type The type of the value. The value must be assignable to - * given type + * @param value the Initial value of the Property. + * @param type the type of the value. The value must be assignable to + * given type. */ public ObjectProperty(Object value, Class type) { @@ -85,20 +97,22 @@ Property.ReadOnlyStatusChangeNotifier { setValue(value); } - /** Creates a new instance of ObjectProperty with the given value, type + /** + * Creates a new instance of ObjectProperty with the given value, type * and read-only mode status. * - * @param value Initial value of the property. - * @param type The type of the value. value must be + * @param value the Initial value of the property. + * @param type the type of the value. value must be * assignable to this type. - * @param readOnly Sets the read-only mode. + * @param readOnly Sets the read-only mode. */ public ObjectProperty(Object value, Class type, boolean readOnly) { this(value,type); setReadOnly(readOnly); } - /** Returns the type of the ObjectProperty. The methods + /** + * Returns the type of the ObjectProperty. The methods * getValue and setValue must be compatible * with this type: one must be able to safely cast the value returned * from getValue to the given type and pass any variable @@ -110,7 +124,8 @@ Property.ReadOnlyStatusChangeNotifier { return type; } - /** Gets the value stored in the Property. + /** + * Gets the value stored in the Property. * * @return the value stored in the Property */ @@ -118,7 +133,8 @@ Property.ReadOnlyStatusChangeNotifier { return value; } - /** Returns the value of the ObjectProperty in human readable textual + /** + * Returns the value of the ObjectProperty in human readable textual * format. The return value should be assignable to the * setValue method if the Property is not in read-only * mode. @@ -134,7 +150,8 @@ Property.ReadOnlyStatusChangeNotifier { return null; } - /** Tests if the Property is in read-only mode. In read-only mode calls + /** + * Tests if the Property is in read-only mode. In read-only mode calls * to the method setValue will throw * ReadOnlyExceptions and will not modify the value of the * Property. @@ -146,9 +163,10 @@ Property.ReadOnlyStatusChangeNotifier { return readOnly; } - /** Sets the Property's read-only mode to the specified status. + /** + * Sets the Property's read-only mode to the specified status. * - * @param newStatus new read-only status of the Property + * @param newStatus the new read-only status of the Property. */ public void setReadOnly(boolean newStatus) { if (newStatus != readOnly) { @@ -157,36 +175,37 @@ Property.ReadOnlyStatusChangeNotifier { } } - /** Set the value of the property. This method supports setting from - * Strings if either String is directly + /** + * Sets the value of the property. This method supports setting from + * String if either String is directly * assignable to property type, or the type class contains a string * constructor. * - * @param newValue New value of the property. + * @param newValue the New value of the property. * @throws Property.ReadOnlyException if the object is in * read-only mode - * @throws Property.ConversionException if - * newValue can't be converted into the Property's native + * @throws Property.ConversionException if the + * newValue can't be converted into the Property's native * type directly or through String */ public void setValue(Object newValue) throws Property.ReadOnlyException, Property.ConversionException { - // Check the mode + // Checks the mode if (isReadOnly()) throw new Property.ReadOnlyException(); - // Try to assign the compatible value directly + // Tries to assign the compatible value directly if (newValue == null || type.isAssignableFrom(newValue.getClass())) value = newValue; // Otherwise try to convert the value trough string constructor else try { - // Get the string constructor + // Gets the string constructor Constructor constr = getType().getConstructor(new Class[] { String.class }); - // Create new object from the string + // Creates new object from the string value = constr.newInstance(new Object[] {newValue.toString()}); } catch (java.lang.Exception e) { @@ -198,7 +217,8 @@ Property.ReadOnlyStatusChangeNotifier { /* Events *************************************************************** */ - /** An Event object specifying the ObjectProperty whose value + /** + * An Event object specifying the ObjectProperty whose value * has changed. * @author IT Mill Ltd. * @version @VERSION@ @@ -212,24 +232,27 @@ Property.ReadOnlyStatusChangeNotifier { */ private static final long serialVersionUID = 3256718468479725873L; - /** Constructs a new value change event for this object. + /** + * Constructs a new value change event for this object. * - * @param source source object of the event + * @param source the source object of the event. */ protected ValueChangeEvent(ObjectProperty source) { super(source); } - /** Gets the Property whose read-only state has changed. + /** + * Gets the Property whose read-only state has changed. * - * @return source Property of the event. + * @return source the Property of the event. */ public Property getProperty() { return (Property) getSource(); } } - /** An Event object specifying the Property whose read-only + /** + * An Event object specifying the Property whose read-only * status has been changed. * @author IT Mill Ltd. * @version @VERSION@ @@ -243,7 +266,8 @@ Property.ReadOnlyStatusChangeNotifier { */ private static final long serialVersionUID = 3907208273529616696L; - /** Constructs a new read-only status change event for this object. + /** + * Constructs a new read-only status change event for this object. * * @param source source object of the event */ @@ -251,7 +275,8 @@ Property.ReadOnlyStatusChangeNotifier { super(source); } - /** Gets the Property whose read-only state has changed. + /** + * Gets the Property whose read-only state has changed. * * @return source Property of the event. */ @@ -260,16 +285,18 @@ Property.ReadOnlyStatusChangeNotifier { } } - /** Remove a previously registered value change listener. + /** + * Removes a previously registered value change listener. * - * @param listener listener to be removed + * @param listener the listener to be removed. */ public void removeListener(Property.ValueChangeListener listener) { if (valueChangeListeners != null) valueChangeListeners.remove(listener); } - /** Registers a new value change listener for this ObjectProperty. + /** + * Registers a new value change listener for this ObjectProperty. * * @param listener the new Listener to be registered */ @@ -279,7 +306,8 @@ Property.ReadOnlyStatusChangeNotifier { valueChangeListeners.add(listener); } - /** Registers a new read-only status change listener for this Property. + /** + * Registers a new read-only status change listener for this Property. * * @param listener the new Listener to be registered */ @@ -289,16 +317,18 @@ Property.ReadOnlyStatusChangeNotifier { readOnlyStatusChangeListeners.add(listener); } - /** Remove a previously registered read-only status change listener. + /** + * Removes a previously registered read-only status change listener. * - * @param listener listener to be removed + * @param listener the listener to be removed. */ public void removeListener(Property.ReadOnlyStatusChangeListener listener) { if (readOnlyStatusChangeListeners != null) readOnlyStatusChangeListeners.remove(listener); } - /** Send a value change event to all registered listeners. + /** + * Sends a value change event to all registered listeners. */ private void fireValueChange() { if (valueChangeListeners != null) { @@ -310,7 +340,8 @@ Property.ReadOnlyStatusChangeNotifier { } } - /** Send a read only status change event to all registered listeners. + /** + * Sends a read only status change event to all registered listeners. */ private void fireReadOnlyStatusChange() { if (readOnlyStatusChangeListeners != null) { diff --git a/src/com/itmill/toolkit/data/util/PropertysetItem.java b/src/com/itmill/toolkit/data/util/PropertysetItem.java index 744a9c9d8e..f2fb4c9279 100644 --- a/src/com/itmill/toolkit/data/util/PropertysetItem.java +++ b/src/com/itmill/toolkit/data/util/PropertysetItem.java @@ -40,7 +40,7 @@ import com.itmill.toolkit.data.Property; /** * Class for handling a set of identified Properties. The elements contained in - * a MapItem can be referenced using locally unique identifiers. + * a MapItem can be referenced using locally unique identifiers. * The class supports listeners who are interested in changes to the Property * set managed by the class. * @@ -54,13 +54,19 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, /* Private representation of the item *********************************** */ - /** Mapping from property id to property */ + /** + * Mapping from property id to property. + */ private HashMap map = new HashMap(); - /** List of all property ids to maintain the order */ + /** + * List of all property ids to maintain the order. + */ private LinkedList list = new LinkedList(); - /** List of property set modification listeners */ + /** + * List of property set modification listeners. + */ private LinkedList propertySetChangeListeners = null; /* Item methods ******************************************************** */ @@ -71,7 +77,7 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, * returned. * * @param id - * identifier of the Property to get + * the identifier of the Property to get. * @return the Property with the given ID or null */ public Property getItemProperty(Object id) { @@ -96,7 +102,7 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, * false. * * @param id - * ID of the Property to be removed + * the ID of the Property to be removed. * @return true if the operation succeeded false * if not */ @@ -118,9 +124,9 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, * Tries to add a new Property into the Item. * * @param id - * ID of the new Property + * the ID of the new Property. * @param property - * the Property to be added and associated with id + * the Property to be added and associated with the id. * @return true if the operation succeeded, * false if not */ @@ -198,7 +204,7 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, * Registers a new property set change listener for this Item. * * @param listener - * The new Listener to be registered. + * the new Listener to be registered. */ public void addListener(Item.PropertySetChangeListener listener) { if (propertySetChangeListeners == null) @@ -210,14 +216,16 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, * Removes a previously registered property set change listener. * * @param listener - * Listener to be removed. + * the Listener to be removed. */ public void removeListener(Item.PropertySetChangeListener listener) { if (propertySetChangeListeners != null) propertySetChangeListeners.remove(listener); } - /** Send a Property set change event to all interested listeners */ + /** + * Sends a Property set change event to all interested listeners. + */ private void fireItemPropertySetChange() { if (propertySetChangeListeners != null) { Object[] l = propertySetChangeListeners.toArray(); @@ -228,7 +236,25 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, .itemPropertySetChange(event); } } - + + /** + * Creates and returns a copy of this object. + *

+ * The method clone performs a shallow copy of the PropertysetItem. + *

+ *

+ * Note : All arrays are considered to implement the interface Cloneable. + * Otherwise, this method creates a new instance of the class of this object + * and initializes all its fields with exactly the contents of the corresponding + * fields of this object, as if by assignment, the contents of the fields are not + * themselves cloned. Thus, this method performs a "shallow copy" of this object, + * not a "deep copy" operation. + *

+ * @throws CloneNotSupportedException + * if the object's class does not support the Cloneable interface. + * + * @see java.lang.Object#clone() + */ public Object clone() throws CloneNotSupportedException { PropertysetItem npsi = new PropertysetItem(); @@ -241,7 +267,14 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, return npsi; } - + + /** + * Returns true if and only if the argument is not null and is a + * Boolean object that represents the same boolean value as this object. + * @param obj the object to compare with. + * @return true if the Boolean objects represent the same value otherwise false. + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { if (obj == null || !(obj instanceof PropertysetItem)) @@ -271,7 +304,12 @@ public class PropertysetItem implements Item, Item.PropertySetChangeNotifier, return true; } - + + /** + * Returns the hash code value for this list. + * @return the hash code value. + * @see java.lang.Object#hashCode() + */ public int hashCode() { return (list == null ? 0 : list.hashCode()) diff --git a/src/com/itmill/toolkit/data/util/QueryContainer.java b/src/com/itmill/toolkit/data/util/QueryContainer.java index 33febfe58c..e7ab940892 100644 --- a/src/com/itmill/toolkit/data/util/QueryContainer.java +++ b/src/com/itmill/toolkit/data/util/QueryContainer.java @@ -99,7 +99,7 @@ public class QueryContainer implements Container, Container.Ordered, /** * Constructs a new QueryContainer with the specified - * queryStatement + * queryStatement. * * @param queryStatement * Database query @@ -121,7 +121,7 @@ public class QueryContainer implements Container, Container.Ordered, /** * Constructs a new QueryContainer with the specified - * queryStatement using the default resultset type and default resultset concurrency + * queryStatement using the default resultset type and default resultset concurrency. * * @param queryStatement * Database query @@ -140,9 +140,11 @@ public class QueryContainer implements Container, Container.Ordered, /** *

- * The init method s invoked by the constructor. This - * method fills the container with the items and properties + * Fills the container with the items and properties. Invoked by the constructor. *

+ * @throws SQLException + * when parameter initialization fails. + * @see QueryContainer#QueryContainer(String, Connection, int, int). */ private void init() throws SQLException { refresh(); @@ -162,8 +164,7 @@ public class QueryContainer implements Container, Container.Ordered, /** *

- * The refresh method refreshes the items in the container. - * This method will update the latest data to the container. + * Restores the items in the container. This method will update the latest data to the container. *

* Note : This method should be used to update the container with the latest items. * @throws SQLException @@ -181,8 +182,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The close method closes the statement and nullify the - * statement. + * Releases and nullify the statement. * * @throws SQLException * when database operation fails @@ -195,8 +195,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The getItem method gets the Item with the given Item ID - * from the Container. + * Gets the Item with the given Item ID from the Container. * * @param id * ID of the Item to retrieve @@ -209,8 +208,7 @@ public class QueryContainer implements Container, Container.Ordered, /** *

- * The getContainerPropertyIds method gets the collection of - * propertyId from the Container. + * Gets the collection of propertyId from the Container. *

* * @return Collection of Property ID. @@ -221,9 +219,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The getItemIds method gets the collection of all the item id in the container. - *

+ * Gets the collection of all the item id in the container. * * @return collection of Item IDs */ @@ -236,8 +232,7 @@ public class QueryContainer implements Container, Container.Ordered, /** *

- * The getContainerProperty method gets the property - * identified by the given itemId and propertyId from the container.If the + * Gets the property identified by the given itemId and propertyId from the container.If the * container does not contain the property null is returned. *

* @@ -266,11 +261,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The getType gets the data type of all properties - * identified by the given type ID. - *

- * + * Gets the data type of all properties identified by the given type ID. * @param id * ID identifying the Properties * @@ -282,21 +273,17 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The size method gets the number of items in the container. + * Gets the number of items in the container. * * @return the number of items in the container. */ - public int size() { return size; } /** - *

- * The containsId method returns true if given - * id is there in container else false. - *

- * + * Tests if the list contains the specified Item. Returns true if + * given id is there in container else false. * @param id * ID the of Item to be tested. */ @@ -312,23 +299,23 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The addItem method creates a new Item with the given ID - * into the Container. + * Creates a new Item with the given ID into the Container. * - * @param arg0 + * @param itemId * ID of the Item to be created. + * + * @return Created new Item, or null if it fails. * * @throws UnsupportedOperationException * if the addItem method is not supported. */ - public Item addItem(Object arg0) throws UnsupportedOperationException { + public Item addItem(Object itemId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The addItem method creates a new Item into the Container, - * and assign it an ID. - * + * Creates a new Item into the Container, and assign it an ID. + * @return ID of the newly created Item, or null if it fails. * @throws UnsupportedOperationException * if the addItem method is not supported. */ @@ -337,54 +324,52 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The addItem method removes the Item identified by ItemId - * from the Container. - * + * Removes the Item identified by ItemId from the Container. + * @param itemId + * ID of the Item to remove. + * @return true if the operation succeeded, otherwise false. * @throws UnsupportedOperationException * if the removeItem method is not supported. */ - public boolean removeItem(Object arg0) throws UnsupportedOperationException { + public boolean removeItem(Object itemId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The addContainerProperty method adds a new Property to all - * Items in the Container. + * Adds a new Property to all Items in the Container. * - * @param arg0 + * @param propertyId * ID of the Property - * @param arg1 + * @param type * Data type of the new Property - * @param arg2 - * The value all created Properties are initialized to - * + * @param defaultValue + * The value all created Properties are initialized to. + * @return true if the operation succeeded, otherwise false. * @throws UnsupportedOperationException * if the addContainerProperty method is not supported. */ - public boolean addContainerProperty(Object arg0, Class arg1, Object arg2) + public boolean addContainerProperty(Object propertyId, Class type, Object defaultValue) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The removeContainerProperty method removes a Property - * specified by the given Property ID from the Container. + * Removes a Property specified by the given Property ID from the Container. * - * @param arg0 + * @param propertyId * ID of the Property to remove - * + * @return true if the operation succeeded, otherwise false. * @throws UnsupportedOperationException * if the removeContainerProperty method is not supported. */ - public boolean removeContainerProperty(Object arg0) + public boolean removeContainerProperty(Object propertyId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The removeAllItems method removes all Items from the - * Container - * + * Removes all Items from the Container. + * @return true if the operation succeeded, otherwise false. * @throws UnsupportedOperationException * if the removeAllItems method is not supported. */ @@ -393,36 +378,38 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The addItemAfter method add new item after the given item. + * Adds new item after the given item. * - * @param arg0 + * @param previousItemId * Id of the previous item in ordered container. - * @param arg1 + * @param newItemId * Id of the new item to be added. + * @return Returns new item or null if the operation fails. * @throws UnsupportedOperationException * if the addItemAfter method is not supported. */ - public Item addItemAfter(Object arg0, Object arg1) + public Item addItemAfter(Object previousItemId, Object newItemId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The addItemAfter method add new item after the given item. + * Adds new item after the given item. * - * @param arg0 + * @param previousItemId * Id of the previous item in ordered container. + * @return Returns item id created new item or null if the operation fails. + * @throws UnsupportedOperationException + * if the addItemAfter method is not supported. */ - public Object addItemAfter(Object arg0) + public Object addItemAfter(Object previousItemId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - *

- * The firstItemId method returns id of first item in the - * Container. - *

+ * Returns id of first item in the Container. + * @return ID of the first Item in the list. */ public Object firstItemId() { if (size < 1) @@ -431,10 +418,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The isFirstId method return true if given - * id is first id at first index. - *

+ * Returns true if given id is first id at first index. * * @param id * ID of an Item in the Container. @@ -445,13 +429,11 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The isLastId method return true if given id - * is last id at last index - *

+ * Returns true if given id is last id at last index. * * @param id * ID of an Item in the Container + * */ public boolean isLastId(Object id) { return size > 0 && (id instanceof Integer) @@ -459,10 +441,8 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The lastItemId method returns id of last item in the - * Container. - *

+ * Returns id of last item in the Container. + * @return ID of the last Item. */ public Object lastItemId() { if (size < 1) @@ -471,13 +451,11 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The nextItemId method return id of next item in container - * at next index. - *

+ * Returns id of next item in container at next index. * * @param id * ID of an Item in the Container. + * @return ID of the next Item or null. */ public Object nextItemId(Object id) { if (size < 1 || !(id instanceof Integer)) @@ -489,14 +467,12 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The prevItemId method return id of previous item in - * container at previous index. - *

+ * Returns id of previous item in container at previous index. * * @param id * ID of an Item in the Container. - */ + * @return ID of the previous Item or null. + */ public Object prevItemId(Object id) { if (size < 1 || !(id instanceof Integer)) return null; @@ -507,9 +483,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

* The Row class implements methods of Item. - *

*/ /** Query result row */ class Row implements Item { @@ -521,30 +495,23 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The addItemProperty method adds the item property. - *

- * - * @param arg0 + * Adds the item property. + * @param id * ID of the new Property. - * @param arg1 + * @param property * Property to be added and associated with ID. + * @return true if the operation succeeded, otherwise false. * @throws UnsupportedOperationException * if the addItemProperty method is not supported. */ - public boolean addItemProperty(Object arg0, Property arg1) + public boolean addItemProperty(Object id, Property property) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - *

- * The getItemProperty gets the property corresponding to - * the given property ID stored in the Item. If the Item does not - * contain the Property, null is returned. - *

- * - * @param id + * Gets the property corresponding to the given property ID stored in the Item. + * @param propertyId * identifier of the Property to get * @return the Property with the given ID or null */ @@ -553,11 +520,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - *

- * The getItemPropertyIds method gets the collection of - * property IDs stored in the Item. - *

- * + * Gets the collection of property IDs stored in the Item. * @return unmodifiable collection containing IDs of the Properties * stored the Item. */ @@ -567,15 +530,14 @@ public class QueryContainer implements Container, Container.Ordered, /** *

- * The removeItemProperty method removes given item - * property return true if the item property is removed + * Removes given item property return true if the item property is removed * false if not. *

- * + * @param id ID of the Property to be removed. * @throws UnsupportedOperationException * if the removeItemProperty is not supported. */ - public boolean removeItemProperty(Object arg0) + public boolean removeItemProperty(Object id) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } @@ -583,7 +545,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The finalize method closes the statement. + * Closes the statement. * * @see #close() */ @@ -596,42 +558,42 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The addItemAt method adds the given item at the position - * of given index. + * Adds the given item at the position of given index. * - * @param arg0 + * @param index * Index to add the new item. - * @param arg1 + * @param newItemId * Id of the new item to be added. - * + * @return Returns new item or null if the operation fails. * @throws UnsupportedOperationException + * if the addItemAt is not supported. */ - public Item addItemAt(int arg0, Object arg1) + public Item addItemAt(int index, Object newItemId) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The addItemAt method adds the item at the position of - * provided index in the container. + * Adds the item at the position of provided index in the container. * - * @param arg0 + * @param index * Index to add the new item. + * @return Returns item id created new item or null if the operation fails. * * @throws UnsupportedOperationException * if the addItemAt is not supported. */ - public Object addItemAt(int arg0) throws UnsupportedOperationException { + public Object addItemAt(int index) throws UnsupportedOperationException { throw new UnsupportedOperationException(); } /** - * The getIdByIndex method gets the Index id in the - * container. + * Gets the Index id in the container. * * @param index * Index Id. + * @return ID in the given index. */ public Object getIdByIndex(int index) { if (size < 1 || index < 0 || index >= size) @@ -640,8 +602,7 @@ public class QueryContainer implements Container, Container.Ordered, } /** - * The indexOfId gets the index of the Item corresponding to - * id in the container. + * Gets the index of the Item corresponding to id in the container. * * @param id * ID of an Item in the Container diff --git a/src/com/itmill/toolkit/data/validator/CompositeValidator.java b/src/com/itmill/toolkit/data/validator/CompositeValidator.java index 90c01f9eed..cb3bbae900 100644 --- a/src/com/itmill/toolkit/data/validator/CompositeValidator.java +++ b/src/com/itmill/toolkit/data/validator/CompositeValidator.java @@ -35,13 +35,12 @@ import java.util.LinkedList; import com.itmill.toolkit.data.*; -/** Composite validator. - * - * This validator allows you to chain (compose) many validators +/** + * The CompositeValidator allows you to chain (compose) many validators * to validate one field. The contained validators may be required * to all validate the value to validate or it may be enough that * one contained validator validates the value. This behaviour is - * controlled by the modes AND and OR. + * controlled by the modes AND and OR. * * @author IT Mill Ltd. * @version @VERSION@ @@ -49,43 +48,58 @@ import com.itmill.toolkit.data.*; */ public class CompositeValidator implements Validator { - /** The validators are combined with AND clause: validity of the + /** + * The validators are combined with AND clause: validity of the * composite implies validity of the all validators it is composed of * must be valid. */ public static final int MODE_AND = 0; - /** The validators are combined with OR clause: validity of the + /** + * The validators are combined with OR clause: validity of the * composite implies that some of validators it is composed of * must be valid. */ public static final int MODE_OR = 1; - /** The validators are combined with and clause: validity of the + /** + * The validators are combined with and clause: validity of the * composite implies validity of the all validators it is composed of */ public static final int MODE_DEFAULT = MODE_AND; - /** Operation mode */ + /** + * Operation mode. + */ private int mode = MODE_DEFAULT; - /** List of contained validators */ + /** + * List of contained validators. + */ private LinkedList validators = new LinkedList(); - /** Error message */ + /** + * Error message. + */ private String errorMessage; - /** Construct composite validator in AND mode without error message */ + /** + * Construct composite validator in AND mode without error message. + */ public CompositeValidator() { } - /** Construct composite validator in given mode */ + /** + * Constructs composite validator in given mode. + */ public CompositeValidator(int mode, String errorMessage) { setMode(mode); setErrorMessage(errorMessage); } - /** Validate the the given value. + /** + * Validates the given value. + *

* The value is valid, if: *