From: Jani Laakso
+ * Gets a window by name. Returns
+ * Sets the user of the application instance. An application instance may have
+ * a user associated to it. This can be set in login procedure or application initialization.
+ *
+ * A component performing the user login procedure can assign the user property
+ * of the application and make the user object available to other components
+ * of the application.
+ *
+ * Main initializer of the application. The
+ * Note that this theme can be overridden by the windows.
+ * Sets the mainWindow. If the main window is not explicitly set, the main window
+ * defaults to first created window. Setting window as a main window of this
+ * application also adds the window to this application.
+ * An event that characterizes a change in the current selection.
+ * Desctop application just closes the application window and web-application redirects
+ * the browser to application main URL.
+ *
+ * Invoked by the terminal on any exception that occurs in application and is thrown by
+ * the
* You can safely override this method in your application in order to direct the errors
* to some other destination (for example log).
- *
+ *
* The application context is the environment where the application is
* running in.
+ *
+ * The license is initialized by the
+ * The license is initialized by the 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.Application
needs to do is implement the init()
+ * Application
needs to do is implement the init
method
* where it creates the windows it needs to perform its function. Note that all
* applications must have at least one window: the main window. The first
* unnamed window constructed by an application automatically becomes the main
@@ -164,9 +164,10 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
private Focusable pendingFocus;
/**
- * Gets a window by name. Returns null
if the application is
- * not running or it does not contain a window corresponding to
- * name
.
+ * null
if the application is not
+ * running or it does not contain a window corresponding to the name.
+ * Window
to add
* @throws IllegalArgumentException
* if a window with the same name as the new window already
- * exists in the application
+ * exists in the application.
* @throws NullPointerException
* if the given Window
or its name is
* null
@@ -257,10 +258,10 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Removes the specified window from the application.
+ * Removes the specified window from the application.
*
* @param window
- * The window to be removed
+ * The window to be removed.
*/
public void removeWindow(Window window) {
if (window != null && windows.contains(window)) {
@@ -297,11 +298,15 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Sets the user of the application instance. An application instance may
- * have a user associated to it. This can be set in login procedure or
- * application initialization. A component performing the user login
- * procedure can assign the user property of the application and make the
- * user object available to other components of the application.
+ * true
if the application is running,
- * false
if not
+ * false
if not.
*/
public boolean isRunning() {
return applicationIsRunning;
@@ -381,18 +386,19 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Main initializer of the application. This method is called by the
+ * init
method is called by the
* framework when the application is started, and it should perform whatever
* initialization operations the application needs, such as creating windows
* and adding components to them.
+ * null
is returned.
+ * Gets the application's theme. The application's theme is the default theme
+ * used by all the windows in it that do not explicitly specify a theme.
+ * If the application theme is not explicitly set, the null
is returned.
*
* @return the name of the application's theme
*/
@@ -401,9 +407,11 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Sets the application's theme. Note that this theme can be overridden by
- * the windows. null
implies the default terminal theme.
- *
+ * Sets the application's theme.
+ * null
+ * implies the default terminal theme.
+ * null
if the property is not found.
*
* @param name
* The name of the property.
@@ -477,8 +486,10 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Add new resource to the application. The resource can be accessed by the
- * user of the application.
+ * Adds new resource to the application. The resource can be accessed
+ * by the user of the application.
+ * @param resource
+ * the resource to add.
*/
public void addResource(ApplicationResource resource) {
@@ -494,7 +505,11 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
keyResourceMap.put(key, resource);
}
- /** Remove resource from the application. */
+ /**
+ * Removes the resource from the application.
+ * @param resource
+ * the resource to remove.
+ */
public void removeResource(ApplicationResource resource) {
Object key = resourceKeyMap.get(resource);
if (key != null) {
@@ -503,7 +518,11 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
}
- /** Get relative uri of the resource */
+ /**
+ * Gets the relative uri of the resource.
+ * @param resource
+ * the resource to get relative location.
+ */
public String getRelativeLocation(ApplicationResource resource) {
// Get the key
@@ -576,19 +595,27 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
return null;
}
- /** Get thed default locale for this application */
+ /**
+ * Gets the default locale for this application.
+ * @return the locale of this application.
+ */
public Locale getLocale() {
if (this.locale != null)
return this.locale;
return Locale.getDefault();
}
- /** Set the default locale for this application */
+ /**
+ * Sets the default locale for this application.
+ * @param locale Locale object
+ *
+ */
public void setLocale(Locale locale) {
this.locale = locale;
}
/**
+ * null
+ */
public Object getPreviousUser() {
return prevUser;
}
- /** Get the application where the user change occurred */
+ /**
+ * Gets the application where the user change occurred.
+ * @return Application
+ */
public Application getApplication() {
return (Application) getSource();
}
}
/**
- * Public interface for listening application user changes
+ * The UserChangeListener
interface for listening application user changes.
*
* @version
* @VERSION@
@@ -642,18 +684,30 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
*/
public interface UserChangeListener extends EventListener {
- /** Invoked when the application user has changed */
+ /**
+ * The applicationUserChanged
method Invoked when the application user has changed.
+ * @param event
+ * change event.
+ */
public void applicationUserChanged(Application.UserChangeEvent event);
}
- /** Add user change listener */
+ /**
+ * Adds user change listener.
+ * @param listener
+ * user change listener to add.
+ */
public void addListener(UserChangeListener listener) {
if (userChangeListeners == null)
userChangeListeners = new LinkedList();
userChangeListeners.add(listener);
}
- /** Remove user change listener */
+ /**
+ * Removes user change listener.
+ * @param listener
+ * user change listener to remove.
+ */
public void removeListener(UserChangeListener listener) {
if (userChangeListeners == null)
return;
@@ -683,18 +737,25 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
this.window = window;
}
- /** Get the detached window */
+ /**
+ * Gets the detached window.
+ * @return detached window
+ */
public Window getWindow() {
return window;
}
- /** Get the application from which the window was detached */
+ /**
+ * Gets the application from which the window was detached.
+ * @return Application
+ */
public Application getApplication() {
return (Application) getSource();
}
}
/** Window attach event */
+
public class WindowAttachEvent extends EventObject {
/**
@@ -705,7 +766,7 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
private Window window;
/**
- * Create event.
+ * Creates event.
*
* @param window
* Attached window.
@@ -715,12 +776,18 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
this.window = window;
}
- /** Get the attached window */
+ /**
+ * Gets the attached window.
+ * @return attached window.
+ */
public Window getWindow() {
return window;
}
- /** Get the application to which the window was attached */
+ /**
+ * Gets the application to which the window was attached.
+ * @return Application.
+ */
public Application getApplication() {
return (Application) getSource();
}
@@ -729,32 +796,52 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
/** Window attach listener interface */
public interface WindowAttachListener {
- /** Window attached */
+ /**
+ * Window attached
+ * @param event
+ * change event.
+ */
public void windowAttached(WindowAttachEvent event);
}
/** Window detach listener interface */
public interface WindowDetachListener {
- /** Window attached */
+ /**
+ * Window detached.
+ * @param event
+ * change event.
+ */
public void windowDetached(WindowDetachEvent event);
}
- /** Add window attach listener */
+ /**
+ * Adds window attach listener.
+ * @param listener
+ * window attach listener to add.
+ */
public void addListener(WindowAttachListener listener) {
if (windowAttachListeners == null)
windowAttachListeners = new LinkedList();
windowAttachListeners.add(listener);
}
- /** Add window detach listener */
+ /**
+ * Adds window detach listener.
+ * @param listener
+ * window detach listener to add.
+ */
public void addListener(WindowDetachListener listener) {
if (windowDetachListeners == null)
windowDetachListeners = new LinkedList();
windowDetachListeners.add(listener);
}
- /** Remove window attach listener */
+ /**
+ * Removes window attach listener.
+ * @param listener
+ * window attach listener to remove.
+ */
public void removeListener(WindowAttachListener listener) {
if (windowAttachListeners != null) {
windowAttachListeners.remove(listener);
@@ -763,7 +850,11 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
}
- /** Remove window detach listener */
+ /**
+ * Removes window detach listener.
+ * @param listener
+ * window detach listener to remove.
+ */
public void removeListener(WindowDetachListener listener) {
if (windowDetachListeners != null) {
windowDetachListeners.remove(listener);
@@ -773,11 +864,13 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
}
/**
- * Returns the URL user is redirected to on application close. If the URL is
- * null, the application is closed normally as defined by the application
- * running environment: Desctop application just closes the application
- * window and web-application redirects the browser to application main URL.
- *
+ * Returns the URL user is redirected to on application close.If the URL
+ * is null
, the application is closed normally as defined by
+ * the application running environment.
+ * null
,
+ * the application is closed normally as defined by the application running environment:
+ * Desctop application just closes the application window and web-application redirects
+ * the browser to application main URL.
*
* @param logoutURL
* The logoutURL to set
@@ -797,12 +890,18 @@ public abstract class Application implements URIHandler, Terminal.ErrorListener
this.logoutURL = logoutURL;
}
- /** This method is invoked by the terminal on any exception that occurs in application
- * and is thrown by the setVariable() to the terminal. The default implementation sets
- * the exceptions as ComponentErrors to the component that initiated the exception.
+ /**
+ * setVariable
to the terminal. The default implementation sets
+ * the exceptions as ComponentErrors
to the component that initiated the exception.
+ * ApplicationServlet
class before application
+ * is started. The license-file can not be found in WEB-INF/itmill-toolkit-license.xml
,
+ * you can set its source in application init
method.
+ * ApplicationServlet
before application
+ * is started. Changing the license after application init
method has no effect.
+ *
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.
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. - * + *
* @returntrue
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
.
- *
+ *
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.
+ *
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.
- *
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.
+ *
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.
+ *
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.
+ *
* 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.
+ *
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. * @returntrue
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.
+ *
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.
+ *
+ * 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.
+ *
+ * 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
* be changed through the implementing class.
- *
+ *
* 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.
+ *
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
- * ReadOnlyException
s 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.
+ *
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
- * ValueChangeEvent
s 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.
+ *
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
- * ReadOnlyStatusChangeEvent
s 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.
+ *
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()}.
+ *
+ * Lists all validators currently registered for the object. If no
* validators are registered, returns null
.
+ *
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
.
+ *
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
+ *
+ * Checks the validabtable object accept invalid values.The default value
+ * is true
.
+ *
+ * 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. TheValidatable#isValid(Object)
iterates all
* registered Validator
s, 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.
+ * 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.
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.
+ *
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)}.
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
.
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. * @returntrue
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. * @returntrue
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. * @returntrue
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)}.
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
.
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. + *
* @returntrue
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 ReadOnlyException
s
+ /**
+ * 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
* String
s 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
* ReadOnlyException
s 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
- * String
s 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; } - + + /** + * Returnstrue
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.
*
- * 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.
*
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.
*
- * The getItemIds
method gets the collection of all the item id in the container.
- *
- * 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.
*
- * The getType
gets the data type of all properties
- * identified by the given type ID.
- *
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.
- *
- * The isFirstId
method return true
if given
- * id is first id at first index.
- *
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
- *
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.
- *
- * The nextItemId
method return id of next item in container
- * at next index.
- *
- * The prevItemId
method return id of previous item in
- * container at previous index.
- *
* The Row
class implements methods of Item.
- *
- * The addItemProperty
method adds the item property.
- *
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.
- *
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.
- *
- * 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.
*
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: *
MODE_AND
: All of the sub-validators are valid
@@ -95,6 +109,10 @@ public class CompositeValidator implements Validator {
* If the value is invalid, validation error is thrown. If the
* error message is set (non-null), it is used. If the error message
* has not been set, the first error occurred is thrown.
+ *
+ * @param value the value to check.
+ * @throws Validator.InvalidValueException
+ * if the value is not valid.
*/
public void validate(Object value) throws Validator.InvalidValueException {
switch (mode) {
@@ -117,15 +135,17 @@ public class CompositeValidator implements Validator {
if (em != null) throw new Validator.InvalidValueException(em);
else throw first;
}
- throw new IllegalStateException("The valitor is in unsupported operation mode");
+ throw new IllegalStateException("The validator is in unsupported operation mode");
}
- /** Check the validity of the the given value.
+ /**
+ * Checks the validity of the the given value.
* The value is valid, if:
* MODE_AND
: All of the sub-validators are valid
* MODE_OR
: Any of the sub-validators are valid
* MODE_AND
or MODE_OR
.
*/
@@ -156,11 +177,13 @@ public class CompositeValidator implements Validator {
return mode;
}
- /** Set the mode of the validator. The valid modes are:
+ /**
+ * Sets the mode of the validator. The valid modes are:
* MODE_AND
(default)
* MODE_OR
* If the component contains
* directly or recursively (it contains another composite
* containing the validator) validators compatible with given type they
- * are returned. This only applies to AND mode composite
+ * are returned. This only applies to AND
mode composite
* validators.
If the validator is in OR mode or does not contain any + *
If the validator is in OR
mode or does not contain any
* validators of given type null is returned.
true
for valid value, otherwise false
.
*/
public boolean isValid(Object value) {
return allowNull ? value == null : value != null;
}
- /** True if nulls are allowed.
+ /**
+ * Returns true
if nulls are allowed otherwise false
.
*/
public final boolean isNullAllowed() {
return allowNull;
}
- /** Sets if nulls are to be allowed.
- * @param allowNull - Do we allow nulls?
+ /**
+ * Sets if nulls are to be allowed.
+ * @param allowNull Do we allow nulls?
*/
public void setNullAllowed(boolean allowNull) {
this.allowNull = allowNull;
}
- /** Get the error message that is displayed in case the
+ /**
+ * Gets the error message that is displayed in case the
* value is invalid.
+ * @return the Error Message.
*/
public String getErrorMessage() {
return errorMessage;
}
- /** Set the error message to be displayed on invalid
+ /**
+ * Sets the error message to be displayed on invalid
* value.
+ * @param errorMessage
+ * the Error Message to set.
*/
public void setErrorMessage(String errorMessage) {
this.errorMessage = errorMessage;
diff --git a/src/com/itmill/toolkit/data/validator/StringLengthValidator.java b/src/com/itmill/toolkit/data/validator/StringLengthValidator.java
index 63dd22f200..bfeb55b5b9 100644
--- a/src/com/itmill/toolkit/data/validator/StringLengthValidator.java
+++ b/src/com/itmill/toolkit/data/validator/StringLengthValidator.java
@@ -30,16 +30,8 @@ package com.itmill.toolkit.data.validator;
import com.itmill.toolkit.data.*;
-
-/**
- * @author IT Mill Ltd.
- *
- * To change this generated comment edit the template variable "typecomment":
- * Window>Preferences>Java>Templates.
- * To enable and disable the creation of type comments go to
- * Window>Preferences>Java>Code Generation.
- */
-/** This validator is used to validate the lenght of strings.
+/**
+ * This StringLengthValidator
is used to validate the length of strings.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -52,21 +44,23 @@ public class StringLengthValidator implements Validator {
private boolean allowNull = true;
private String errorMessage;
- /** Create a new StringLengthValidator with a given error message.
+ /**
+ * Creates a new StringLengthValidator with a given error message.
*
- * @param errorMessage - The message to display in case the value does not validate.
+ * @param errorMessage the message to display in case the value does not validate.
*/
public StringLengthValidator(String errorMessage) {
setErrorMessage(errorMessage);
}
- /** Create a new StringLenghtValidator with a given error message,
- * permissable lenghts and null-string allowance.
+ /**
+ * Creates a new StringLengthValidator with a given error message,
+ * permissable lengths and null-string allowance.
*
- * @param errorMessage - The message to display in case the value does not validate.
- * @param minLenght - The minimum permissable lenght of the string.
- * @param maxLenght - The maximum permissable lenght of the string.
- * @param allowNull - Are null strings permissable?
+ * @param errorMessage the message to display in case the value does not validate.
+ * @param minLength the minimum permissable length of the string.
+ * @param maxLength the maximum permissable length of the string.
+ * @param allowNull Are null strings permissable?
*/
public StringLengthValidator(
String errorMessage,
@@ -79,8 +73,11 @@ public class StringLengthValidator implements Validator {
setNullAllowed(allowNull);
}
- /** Validate the value.
- * @param value - The value to validate.
+ /**
+ * Validates the value.
+ * @param value the value to validate.
+ * @throws Validator.InvalidValueException
+ * if the value was invalid.
*/
public void validate(Object value) throws Validator.InvalidValueException {
if (value == null && !allowNull)
@@ -94,8 +91,10 @@ public class StringLengthValidator implements Validator {
throw new Validator.InvalidValueException(errorMessage);
}
- /** True if the value is valid.
- * @param value - The value to validate.
+ /**
+ * Checks if the given value is valid.
+ * @param value the value to validate.
+ * @return true
for valid value, otherwise false
.
*/
public boolean isValid(Object value) {
if (value == null && !allowNull)
@@ -110,32 +109,40 @@ public class StringLengthValidator implements Validator {
return true;
}
- /** True if null strings are allowed.
+ /**
+ * Returns true
if null strings are allowed.
+ * @return true
if allows null string, otherwise false
.
*/
public final boolean isNullAllowed() {
return allowNull;
}
- /** Get the maximum permissable length of the string.
+ /**
+ * Gets the maximum permissable length of the string.
+ * @return the maximum length of the string.
*/
public final int getMaxLength() {
return maxLength;
}
- /** Get the minimum permissable lenght of the string.
+ /**
+ * Gets the minimum permissable length of the string.
+ * @return the minimum length of the string.
*/
public final int getMinLength() {
return minLength;
}
- /** Sets wheter null-strings are to be allowed.
+ /**
+ * Sets whether null-strings are to be allowed.
*/
public void setNullAllowed(boolean allowNull) {
this.allowNull = allowNull;
}
- /** Set the maximum permissable length of the string.
- * @param maxLenght - The lenght to set.
+ /**
+ * Sets the maximum permissable length of the string.
+ * @param maxLength the length to set.
*/
public void setMaxLength(int maxLength) {
if (maxLength < -1)
@@ -143,8 +150,9 @@ public class StringLengthValidator implements Validator {
this.maxLength = maxLength;
}
- /** Sets the minimum permissable lenght.
- * @param minLenght - The lenght to set.
+ /**
+ * Sets the minimum permissable length.
+ * @param minLength the length to set.
*/
public void setMinLength(int minLength) {
if (minLength < -1)
@@ -152,15 +160,20 @@ public class StringLengthValidator implements Validator {
this.minLength = minLength;
}
- /** Gets the message to be displayed in case the
+ /**
+ * Gets the message to be displayed in case the
* value does not validate.
+ * @return the Error Message.
*/
public String getErrorMessage() {
return errorMessage;
}
- /** Sets the message to be displayer in case the
+ /**
+ * Sets the message to be displayer in case the
* value does not validate.
+ * @param errorMessage
+ * the Error Message to set.
*/
public void setErrorMessage(String errorMessage) {
this.errorMessage = errorMessage;
diff --git a/src/com/itmill/toolkit/event/Action.java b/src/com/itmill/toolkit/event/Action.java
index 91d093e54f..34ccd8a192 100644
--- a/src/com/itmill/toolkit/event/Action.java
+++ b/src/com/itmill/toolkit/event/Action.java
@@ -30,7 +30,8 @@ package com.itmill.toolkit.event;
import com.itmill.toolkit.terminal.*;
-/** Implements the action framework. This class contains
+/**
+ * Implements the action framework. This class contains
* subinterfaces for action handling and listing, and for action handler
* registrations and unregistration.
*
@@ -40,108 +41,125 @@ import com.itmill.toolkit.terminal.*;
*/
public class Action {
- /** Action title */
+ /**
+ * Action title.
+ */
private String caption;
- /** Action icon */
+ /**
+ * Action icon.
+ */
private Resource icon = null;
- /** Constructs a new action with the given caption.
+ /**
+ * Constructs a new action with the given caption.
*
- * @param caption caption for the new action.
+ * @param caption the caption for the new action.
*/
public Action(String caption) {
this.caption = caption;
}
- /** Constructs a new action with the given caption string and icon.
+ /**
+ * Constructs a new action with the given caption string and icon.
*
- * @param caption caption for the new action.
- * @param icon icon for the new action
+ * @param caption the caption for the new action.
+ * @param icon the icon for the new action.
*/
public Action(String caption, Resource icon) {
this.caption = caption;
this.icon = icon;
}
- /** Returns the action's caption.
+ /**
+ * Returns the action's caption.
*
- * @return the action's caption as a String
+ * @return the action's caption as a String
.
*/
public String getCaption() {
return caption;
}
- /** Returns the action's icon.
+ /**
+ * Returns the action's icon.
*
- * @return Icon
+ * @return the action's Icon.
*/
public Resource getIcon() {
return icon;
}
- /** Interface implemented by classes who wish to handle actions.
+ /**
+ * Interface implemented by classes who wish to handle actions.
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
*/
public interface Handler {
- /** Returns the list of actions applicable to this handler.
+ /**
+ * Gets the list of actions applicable to this handler.
*
- * @param target The target handler to list actions for. For item
+ * @param target the target handler to list actions for. For item
* containers this is the item id.
- * @param sender The party that would be sending the actions.
+ * @param sender the party that would be sending the actions.
* Most of this is the action container.
+ * @return the list of Action
*/
public Action[] getActions(Object target, Object sender);
- /** Handles an action for the given target. The handler method
+ /**
+ * Handles an action for the given target. The handler method
* may just discard the action if it's not suitable.
*
- * @param action The action to be handled
- * @param sender The sender of the action. This is most often the
+ * @param action the action to be handled.
+ * @param sender the sender of the action. This is most often the
* action container.
- * @param target The target of the action
. For item
+ * @param target the target of the action. For item
* containers this is the item id.
*/
public void handleAction(Action action, Object sender, Object target);
}
- /** Interface implemented by all components where actions can be
+ /**
+ * Interface implemented by all components where actions can be
* registered. This means that the components lets others to register
* as action handlers to it. When the component receives an action
* targeting its contents it should loop all action handlers registered
- * to it and let them hanle the action.
+ * to it and let them handle the action.
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
*/
public interface Container {
- /** Registers a new action handler for this container
+ /**
+ * Registers a new action handler for this container
*
* @param actionHandler the new handler to be added.
*/
public void addActionHandler(Action.Handler actionHandler);
- /** Remove a previously registered action handler for the contents
+ /**
+ * Removes a previously registered action handler for the contents
* of this container.
*
- * @param actionHandler the handler to be removed
+ * @param actionHandler the handler to be removed.
*/
public void removeActionHandler(Action.Handler actionHandler);
}
- /** Sets the caption.
- * @param caption The caption to set
+ /**
+ * Sets the caption.
+ * @param caption the caption to set.
*/
public void setCaption(String caption) {
this.caption = caption;
}
- /** Sets the icon.
- * @param icon The icon to set
+ /**
+ * Sets the icon.
+ * @param icon the icon to set.
*/
public void setIcon(Resource icon) {
this.icon = icon;
diff --git a/src/com/itmill/toolkit/event/EventRouter.java b/src/com/itmill/toolkit/event/EventRouter.java
index 0c04f52a83..d3c1042acd 100644
--- a/src/com/itmill/toolkit/event/EventRouter.java
+++ b/src/com/itmill/toolkit/event/EventRouter.java
@@ -33,7 +33,8 @@ import java.util.LinkedList;
import java.util.Iterator;
import java.lang.reflect.Method;
-/** Event router class implementing the inheritable event
+/**
+ * EventRouter
class implementing the inheritable event
* listening model. For more information on the event model see the
* {@link com.itmill.toolkit.event package documentation}.
*
@@ -43,7 +44,9 @@ import java.lang.reflect.Method;
*/
public class EventRouter implements MethodEventSource {
- /** List of registered listeners. */
+ /**
+ * List of registered listeners.
+ */
private LinkedList listenerList = null;
/* Registers a new listener with the specified activation method to
@@ -143,15 +146,18 @@ public class EventRouter implements MethodEventSource {
}
}
- /** Remove all listeners from event router */
+ /**
+ * Removes all listeners from event router.
+ */
public void removeAllListeners() {
listenerList = null;
}
- /** Send an event to all registered listeners. The listeners will decide
+ /**
+ * Sends an event to all registered listeners. The listeners will decide
* if the activation method should be called or not.
*
- * @param event Event to be sent to all listeners
+ * @param event the Event to be sent to all listeners.
*/
public void fireEvent(EventObject event) {
diff --git a/src/com/itmill/toolkit/event/ListenerMethod.java b/src/com/itmill/toolkit/event/ListenerMethod.java
index e73becf66b..66ab99868c 100644
--- a/src/com/itmill/toolkit/event/ListenerMethod.java
+++ b/src/com/itmill/toolkit/event/ListenerMethod.java
@@ -32,18 +32,26 @@ import java.util.EventListener;
import java.util.EventObject;
import java.lang.reflect.Method;
-/** One registered event listener. This class contains the listener +/** + *
+ * One registered event listener. This class contains the listener * object reference, listened event type, the trigger method to call when * the event fires, and the optional argument list to pass to the method and - * the index of the argument to replace with the event object. It provides - * several constructors that allow omission of the optional arguments, and - * giving the listener method directly, or having the constructor to reflect - * it using merely the name of the method.
+ * the index of the argument to replace with the event object. + * * - *It should be pointed out that the method + *
+ * This Class provides several constructors that allow omission of the optional + * arguments, and giving the listener method directly, or having the constructor + * to reflect it using merely the name of the method. + *
+ * + *+ * It should be pointed out that the method * {@link #receiveEvent(EventObject event)} is the one that filters out the * events that do not match with the given event type and thus do not result - * in calling of the trigger method.
+ * in calling of the trigger method. + * * * @author IT Mill Ltd. * @version @VERSION@ @@ -51,45 +59,57 @@ import java.lang.reflect.Method; */ public class ListenerMethod implements EventListener { - /** Type of the event that should trigger this listener. Also the + /** + * Type of the event that should trigger this listener. Also the * subclasses of this class are accepted to trigger the listener. */ private Class eventType; - /** The object containing the trigger method, */ + /** + * The object containing the trigger method. + */ private Object object; - /** The trigger method to call when an event passing the given criteria + /** + * The trigger method to call when an event passing the given criteria * fires. */ private Method method; - /** Optional argument set to pass to the trigger method. */ + /** + * Optional argument set to pass to the trigger method. + */ private Object[] arguments; - /** Optional index toarguments
that point out which one
+ /**
+ * Optional index to arguments
that point out which one
* should be replaced with the triggering event object and thus be
* passed to the trigger method.
*/
private int eventArgumentIndex;
- /** Constructs a new event listener from a trigger method, it's + /** + *
+ * Constructs a new event listener from a trigger method, it's * arguments and the argument index specifying which one is replaced - * with the event object when the trigger method is called.
+ * with the event object when the trigger method is called. + * * - *This constructor gets the trigger method as a parameter so it - * does not need to reflect to find it out.
+ *+ * This constructor gets the trigger method as a parameter so it + * does not need to reflect to find it out. + *
* - * @param eventType The event type that is listener listens to. All + * @param eventType the event type that is listener listens to. All * events of this kind (or its subclasses) result in calling the trigger * method. - * @param object The object instance that contains the trigger method + * @param object the object instance that contains the trigger method * @param method the trigger method - * @param arguments arguments to be passed to the trigger method + * @param arguments the arguments to be passed to the trigger method * @param eventArgumentIndex An index to the argument list. This index * points out the argument that is replaced with the event object before * the argument set is passed to the trigger method. If - *eventArgumentIndex
is negative, the triggering event
+ * the eventArgumentIndex is negative, the triggering event
* object will not be passed to the trigger method, though it is still
* called.
* @throws java.lang.IllegalArgumentException if method
@@ -103,15 +123,15 @@ public class ListenerMethod implements EventListener {
int eventArgumentIndex)
throws java.lang.IllegalArgumentException {
- // Check that the object is of correct type
+ // Checks that the object is of correct type
if (!method.getDeclaringClass().isAssignableFrom(object.getClass()))
throw new java.lang.IllegalArgumentException();
- // Check that the event argument is null
+ // Checks that the event argument is null
if (eventArgumentIndex >= 0 && arguments[eventArgumentIndex] != null)
throw new java.lang.IllegalArgumentException();
- // Check the event type is supported by the method
+ // Checks the event type is supported by the method
if (eventArgumentIndex >= 0
&& !method.getParameterTypes()[eventArgumentIndex].isAssignableFrom(
eventType))
@@ -124,26 +144,28 @@ public class ListenerMethod implements EventListener {
this.eventArgumentIndex = eventArgumentIndex;
}
- /** Constructs a new event listener from a trigger method name, it's + /** + *
+ * Constructs a new event listener from a trigger method name, it's
* arguments and the argument index specifying which one is replaced
* with the event object. The actual trigger method is reflected from
* object
, and
* java.lang.IllegalArgumentException
is thrown unless
* exactly one match is found.
- *
- * @param eventType The event type that is listener listens to. All
+ *
object
does not contain the method or it contains more
+ * @param object the object instance that contains the trigger method.
+ * @param methodName the name of the trigger method. If the
+ * object does not contain the method or it contains more
* than one matching methods
* java.lang.IllegalArgumentException
is thrown.
- * @param arguments arguments to be passed to the trigger method
+ * @param arguments the arguments to be passed to the trigger method.
* @param eventArgumentIndex An index to the argument list. This index
* points out the argument that is replaced with the event object before
- * the argument set is passed to the trigger method. If
- * eventArgumentIndex
is negative, the triggering event
+ * the argument set is passed to the trigger method. If the
+ * eventArgumentIndex is negative, the triggering event
* object will not be passed to the trigger method, though it is still
* called.
* @throws java.lang.IllegalArgumentException unless exactly one match
@@ -157,7 +179,7 @@ public class ListenerMethod implements EventListener {
int eventArgumentIndex)
throws java.lang.IllegalArgumentException {
- // Find the correct method
+ // Finds the correct method
Method[] methods = object.getClass().getMethods();
Method method = null;
for (int i = 0; i < methods.length; i++)
@@ -166,11 +188,11 @@ public class ListenerMethod implements EventListener {
if (method == null)
throw new IllegalArgumentException();
- // Check that the event argument is null
+ // Checks that the event argument is null
if (eventArgumentIndex >= 0 && arguments[eventArgumentIndex] != null)
throw new java.lang.IllegalArgumentException();
- // Check the event type is supported by the method
+ // Checks the event type is supported by the method
if (eventArgumentIndex >= 0
&& !method.getParameterTypes()[eventArgumentIndex].isAssignableFrom(
eventType))
@@ -183,20 +205,25 @@ public class ListenerMethod implements EventListener {
this.eventArgumentIndex = eventArgumentIndex;
}
- /** Constructs a new event listener from the trigger method and it's + /** + *
+ * Constructs a new event listener from the trigger method and it's * arguments. Since the the index to the replaced parameter is not * specified the event triggering this listener will not be passed to - * the trigger method.
+ * the trigger method. + * * - *This constructor gets the trigger method as a parameter so it - * does not need to reflect to find it out.
+ *+ * This constructor gets the trigger method as a parameter so it + * does not need to reflect to find it out. + *
* - * @param eventType The event type that is listener listens to. All + * @param eventType the event type that is listener listens to. All * events of this kind (or its subclasses) result in calling the trigger * method. - * @param object The object instance that contains the trigger method - * @param method the trigger method - * @param arguments arguments to be passed to the trigger method + * @param object the object instance that contains the trigger method. + * @param method the trigger method. + * @param arguments the arguments to be passed to the trigger method. * @throws java.lang.IllegalArgumentException ifmethod
* is not a member of object
.
*/
@@ -218,24 +245,29 @@ public class ListenerMethod implements EventListener {
this.eventArgumentIndex = -1;
}
- /** Constructs a new event listener from a trigger method name and + /** + *
+ * Constructs a new event listener from a trigger method name and * it's arguments. Since the the index to the replaced parameter is not * specified the event triggering this listener will not be passed to - * the trigger method.
+ * the trigger method. + * * - *The actual trigger method is reflected from object
,
+ *
+ * The actual trigger method is reflected from object
,
* and java.lang.IllegalArgumentException
is thrown unless
- * exactly one match is found.
object
does not contain the method or it contains more
+ * @param object the object instance that contains the trigger method.
+ * @param methodName the name of the trigger method. If the
+ * object does not contain the method or it contains more
* than one matching methods
* java.lang.IllegalArgumentException
is thrown.
- * @param arguments arguments to be passed to the trigger method
+ * @param arguments the arguments to be passed to the trigger method.
* @throws java.lang.IllegalArgumentException unless exactly one match
* methodName
is found in object
.
*/
@@ -262,25 +294,30 @@ public class ListenerMethod implements EventListener {
this.eventArgumentIndex = -1;
}
- /** Constructs a new event listener from a trigger method. Since the + /** + *
+ * Constructs a new event listener from a trigger method. Since the * argument list is unspecified no parameters are passed to the trigger - * method when the listener is triggered.
+ * method when the listener is triggered. + * * - *This constructor gets the trigger method as a parameter so it - * does not need to reflect to find it out.
+ *+ * This constructor gets the trigger method as a parameter so it + * does not need to reflect to find it out. + *
* - * @param eventType The event type that is listener listens to. All + * @param eventType the event type that is listener listens to. All * events of this kind (or its subclasses) result in calling the trigger * method. - * @param object The object instance that contains the trigger method - * @param method the trigger method + * @param object the object instance that contains the trigger method. + * @param method the trigger method. * @throws java.lang.IllegalArgumentException ifmethod
* is not a member of object
.
*/
public ListenerMethod(Class eventType, Object object, Method method)
throws java.lang.IllegalArgumentException {
- // Check that the object is of correct type
+ // Checks that the object is of correct type
if (!method.getDeclaringClass().isAssignableFrom(object.getClass()))
throw new java.lang.IllegalArgumentException();
@@ -300,20 +337,25 @@ public class ListenerMethod implements EventListener {
throw new IllegalArgumentException();
}
- /** Constructs a new event listener from a trigger method name. Since + /** + *
+ * Constructs a new event listener from a trigger method name. Since * the argument list is unspecified no parameters are passed to the - * trigger method when the listener is triggered.
+ * trigger method when the listener is triggered. + * * - *The actual trigger method is reflected from object
,
+ *
+ * The actual trigger method is reflected from object
,
* and java.lang.IllegalArgumentException
is thrown unless
- * exactly one match is found.
object
does not contain the method or it contains more
+ * @param object the object instance that contains the trigger method.
+ * @param methodName the name of the trigger method. If the
+ * object does not contain the method or it contains more
* than one matching methods
* java.lang.IllegalArgumentException
is thrown.
* @throws java.lang.IllegalArgumentException unless exactly one match
@@ -322,7 +364,7 @@ public class ListenerMethod implements EventListener {
public ListenerMethod(Class eventType, Object object, String methodName)
throws java.lang.IllegalArgumentException {
- // Find the correct method
+ // Finds the correct method
Method[] methods = object.getClass().getMethods();
Method method = null;
for (int i = 0; i < methods.length; i++)
@@ -347,12 +389,13 @@ public class ListenerMethod implements EventListener {
throw new IllegalArgumentException();
}
- /** Receives one event from the EventRouter and calls the trigger
+ /**
+ * Receives one event from the EventRouter
and calls the trigger
* method if it matches with the criteria defined for the listener.
* Only the events of the same or subclass of the specified event
* class result in the trigger method to be called.
*
- * @param event The fired event. Unless the trigger method's
+ * @param event the fired event. Unless the trigger method's
* argument list and the index to the to be replaced argument is
* specified, this event will not be passed to the trigger method.
*/
@@ -387,13 +430,14 @@ public class ListenerMethod implements EventListener {
}
}
- /** Checks if the given object and event match with the ones stored
+ /**
+ * Checks if the given object and event match with the ones stored
* in this listener.
*
- * @param target object to be matched against the object stored by this
- * listener
- * @param eventType type to be tested for equality against the type
- * stored by this listener
+ * @param target the object to be matched against the object stored by this
+ * listener.
+ * @param eventType the type to be tested for equality against the type
+ * stored by this listener.
* @return true
if target
is the same object
* as the one stored in this object and eventType
equals
* the event type stored in this object.
@@ -402,15 +446,16 @@ public class ListenerMethod implements EventListener {
return (target == object) && (eventType.equals(this.eventType));
}
- /** Checks if the given object, event and method match with the ones
+ /**
+ * Checks if the given object, event and method match with the ones
* stored in this listener.
*
- * @param target object to be matched against the object stored by this
- * listener
- * @param eventType type to be tested for equality against the type
- * stored by this listener
- * @param method method to be tested for equality against the method
- * stored by this listener
+ * @param target the object to be matched against the object stored by this
+ * listener.
+ * @param eventType the type to be tested for equality against the type
+ * stored by this listener.
+ * @param method the method to be tested for equality against the method
+ * stored by this listener.
* @return true
if target
is the same object
* as the one stored in this object, eventType
equals
* with the event type stored in this object and method
@@ -421,10 +466,11 @@ public class ListenerMethod implements EventListener {
&& (eventType.equals(this.eventType) && method.equals(this.method));
}
- /** Exception that wraps an exception thrown by an invoked method.
- * When ListenerMethod invokes the target method, it may throw arbitrary
- * exception. The original exception is wrapped into MethodException instance and
- * rethrown by the ListenerMethod.
+ /**
+ * Exception that wraps an exception thrown by an invoked method.
+ * When ListenerMethod
invokes the target method, it may throw arbitrary
+ * exception. The original exception is wrapped into MethodException instance and
+ * rethrown by the ListenerMethod
.
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
@@ -443,18 +489,27 @@ public class ListenerMethod implements EventListener {
super(message);
this.cause = cause;
}
-
+ /**
+ * Retrieves the cause of this throwable or null
if the cause does not exist or not known.
+ * @return the cause of this throwable or null
if the cause is nonexistent or unknown.
+ * @see java.lang.Throwable#getCause()
+ */
public Throwable getCause() {
return this.cause;
}
/**
+ * Returns the error message string of this throwable object.
+ * @return the error message.
* @see java.lang.Throwable#getMessage()
*/
public String getMessage() {
return message;
}
-
+
+ /**
+ * @see java.lang.Throwable#toString()
+ */
public String toString() {
String msg = super.toString();
if (cause != null)
diff --git a/src/com/itmill/toolkit/event/MethodEventSource.java b/src/com/itmill/toolkit/event/MethodEventSource.java
index a98213daa4..4df6d9674f 100644
--- a/src/com/itmill/toolkit/event/MethodEventSource.java
+++ b/src/com/itmill/toolkit/event/MethodEventSource.java
@@ -30,12 +30,17 @@ package com.itmill.toolkit.event;
import java.lang.reflect.Method;
-/** Interface for classes supporting registeration of methods as event - * receivers.
+/** + *+ * Interface for classes supporting registeration of methods as event + * receivers. + *
* - *For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * * @author IT Mill Ltd. * @version @VERSION@ @@ -43,97 +48,122 @@ import java.lang.reflect.Method; */ public interface MethodEventSource { - /**Registers a new event listener with the specified activation + /** + *
+ * Registers a new event listener with the specified activation * method to listen events generated by this component. If the * activation method does not have any arguments the event object will - * not be passed to it when it's called.
+ * not be passed to it when it's called. + * * - *For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * - * @param eventType type of the listened event. Events of this type or + * @param eventType the type of the listened event. Events of this type or * its subclasses activate the listener. - * @param object the object instance who owns the activation method - * @param method the activation method + * @param object the object instance who owns the activation method. + * @param method the activation method. * @throws java.lang.IllegalArgumentException unlessmethod
* has exactly one match in object
*/
public void addListener(Class eventType, Object object, Method method);
- /** Registers a new listener with the specified activation method to + /** + *
+ * Registers a new listener with the specified activation method to * listen events generated by this component. If the activation method * does not have any arguments the event object will not be passed to it - * when it's called.
+ * when it's called. + * * - *This version of addListener
gets the name of the
+ *
+ * This version of addListener
gets the name of the
* activation method as a parameter. The actual method is reflected from
* object
, and unless exactly one match is found,
- * java.lang.IllegalArgumentException
is thrown.
java.lang.IllegalArgumentException
is thrown.
+ *
*
- * For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * - * @param eventType type of the listened event. Events of this type or + * @param eventType the type of the listened event. Events of this type or * its subclasses activate the listener. - * @param object the object instance who owns the activation method - * @param methodName the name of the activation method + * @param object the object instance who owns the activation method. + * @param methodName the name of the activation method. * @throws java.lang.IllegalArgumentException unlessmethod
* has exactly one match in object
*/
public void addListener(Class eventType, Object object, String methodName);
- /** Removes all registered listeners matching the given parameters.
+ /**
+ * Removes all registered listeners matching the given parameters.
* Since this method receives the event type and the listener object as
* parameters, it will unregister all object
's methods that
* are registered to listen to events of type eventType
* generated by this component.
*
- * For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * - * @param eventType exact event type theobject
listens to
- * @param target target object that has registered to listen to events
- * of type eventType
with one or more methods
+ * @param eventType the exact event type the object
listens to.
+ * @param target the target object that has registered to listen to events
+ * of type eventType
with one or more methods.
*/
public void removeListener(Class eventType, Object target);
- /** Removes one registered listener method. The given method owned by
+ /**
+ * Removes one registered listener method. The given method owned by
* the given object will no longer be called when the specified events
* are generated by this component.
*
- * For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * - * @param eventType exact event type theobject
listens to
- * @param target target object that has registered to listen to events
- * of type eventType
with one or more methods
- * @param method the method owned by target
that's
- * registered to listen to events of type eventType
+ * @param eventType the exact event type the object
listens to.
+ * @param target the target object that has registered to listen to events
+ * of type eventType with one or more methods.
+ * @param method the method owned by the target that's
+ * registered to listen to events of type eventType.
*/
public void removeListener(Class eventType, Object target, Method method);
- /** Removes one registered listener method. The given method owned by + /** + *
+ * Removes one registered listener method. The given method owned by * the given object will no longer be called when the specified events - * are generated by this component.
+ * are generated by this component. + * * - *This version of removeListener
gets the name of the
+ *
+ * This version of removeListener
gets the name of the
* activation method as a parameter. The actual method is reflected from
- * target
, and unless exactly one match is found,
- * java.lang.IllegalArgumentException
is thrown.
java.lang.IllegalArgumentException
is thrown.
+ *
*
- * For more information on the inheritable event mechanism + *
+ * For more information on the inheritable event mechanism * see the - * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}.
+ * {@link com.itmill.toolkit.event com.itmill.toolkit.event package documentation}. + * * - * @param eventType exact event type theobject
listens to
- * @param target target object that has registered to listen to events
- * of type eventType
with one or more methods
- * @param methodName name of the method owned by target
- * that's registered to listen to events of type eventType
+ * @param eventType the exact event type the object
listens to.
+ * @param target the target object that has registered to listen to events
+ * of type eventType
with one or more methods.
+ * @param methodName the name of the method owned by target
+ * that's registered to listen to events of type eventType
.
*/
public void removeListener(Class eventType, Object target, String methodName);
}
diff --git a/src/com/itmill/toolkit/service/ApplicationContext.java b/src/com/itmill/toolkit/service/ApplicationContext.java
index d5f413dc35..5486c4189f 100644
--- a/src/com/itmill/toolkit/service/ApplicationContext.java
+++ b/src/com/itmill/toolkit/service/ApplicationContext.java
@@ -33,7 +33,8 @@ import java.util.Collection;
import com.itmill.toolkit.Application;
-/** Application context provides information about the running context of
+/**
+ * ApplicationContext
provides information about the running context of
* the application. Each context is shared by all applications that are open
* for one user. In web-environment this corresponds to HttpSession.
*
@@ -43,7 +44,8 @@ import com.itmill.toolkit.Application;
*/
public interface ApplicationContext {
- /** Returns application context base directory.
+ /**
+ * Returns application context base directory.
*
* Typically an application is deployed in a such way that is
* has application directory. For web applications this directory is the
@@ -55,9 +57,10 @@ public interface ApplicationContext {
*/
public File getBaseDirectory();
- /** Get the applications in this context.
+ /**
+ * Gets the applications in this context.
*
- * Get all applications in this context. Each application context contains
+ * Gets all applications in this context. Each application context contains
* all applications that are open for one user.
*
* @return Collection containing all applications in this context
@@ -65,33 +68,40 @@ public interface ApplicationContext {
public Collection getApplications();
- /** Add transaction listener to this context.
- * @param listener The listener to be added.
+ /**
+ * Adds transaction listener to this context.
+ * @param listener the listener to be added.
* @see TransactionListener
*/
public void addTransactionListener(TransactionListener listener);
- /** Remove transaction listener from this context.
- * @param listener The listener to be removed.
+ /**
+ * Removes transaction listener from this context.
+ * @param listener the listener to be removed.
* @see TransactionListener
*/
public void removeTransactionListener(TransactionListener listener);
- /** Interface for listening the application transaction events.
- * Implementations of this interface can be used to listen all
- * transactions between the client and the application.
+ /**
+ * Interface for listening the application transaction events.
+ * Implementations of this interface can be used to listen all
+ * transactions between the client and the application.
*
*/
public interface TransactionListener {
- /** Invoked at the beginning of every transaction.
- * @param transactionData Data identifying the transaction.
+ /**
+ * Invoked at the beginning of every transaction.
+ * @param application the Application object.
+ * @param transactionData the Data identifying the transaction.
*/
public void transactionStart(Application application, Object transactionData);
- /** Invoked at the end of every transaction.
- * @param transactionData Data identifying the transaction.
+ /**
+ * Invoked at the end of every transaction.
+ * @param applcation the Application object.
+ * @param transactionData the Data identifying the transaction.
*/
public void transactionEnd(Application application, Object transactionData);
diff --git a/src/com/itmill/toolkit/service/FileTypeResolver.java b/src/com/itmill/toolkit/service/FileTypeResolver.java
index b584c9f57a..9e19d41cad 100644
--- a/src/com/itmill/toolkit/service/FileTypeResolver.java
+++ b/src/com/itmill/toolkit/service/FileTypeResolver.java
@@ -37,23 +37,31 @@ import java.util.StringTokenizer;
import com.itmill.toolkit.terminal.Resource;
import com.itmill.toolkit.terminal.ThemeResource;
-/** Utility class that can figure out mime-types and icons related to files.
- * Note that the icons are associated purely to mime-types, so a file
+/**
+ * Utility class that can figure out mime-types and icons related to files.
+ * + * Note : The icons are associated purely to mime-types, so a file * may not have a custom icon accessible with this class. - * + *
* @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 */ public class FileTypeResolver { - /** Default icon given if no icon is specified for a mime-type. */ + /** + * Default icon given if no icon is specified for a mime-type. + */ static public Resource DEFAULT_ICON = new ThemeResource("icon/files/file.gif"); - /** Default mime-type. */ + /** + * Default mime-type. + */ static public String DEFAULT_MIME_TYPE = "application/octet-stream"; - /** Initial file extension to mime-type mapping. */ + /** + * Initial file extension to mime-type mapping. + */ static private String initialExtToMIMEMap = "application/cu-seeme csm cu," + "application/dsptype tsp," @@ -203,10 +211,14 @@ public class FileTypeResolver { + "video/x-sgi-movie movie," + "x-world/x-vrml vrm vrml wrl"; - /** File extension to MIME type mapping. */ + /** + * File extension to MIME type mapping. + */ static private Hashtable extToMIMEMap = new Hashtable(); - /** MIME type to Icon mapping. */ + /** + * MIME type to Icon mapping. + */ static private Hashtable MIMEToIconMap = new Hashtable(); static { @@ -228,19 +240,20 @@ public class FileTypeResolver { addIcon("inode/directory", new ThemeResource("icon/files/folder.gif")); } - /** Gets the mime-type of a file. Currently the mime-type is resolved + /** + * Gets the mime-type of a file. Currently the mime-type is resolved * based only on the file name extension. * - * @param fileName name of the file whose mime-type is requested + * @param fileName the name of the file whose mime-type is requested. * @return mime-typeString
for the given filename
*/
public static String getMIMEType(String fileName) {
- // Check for nulls
+ // Checks for nulls
if (fileName == null)
throw new NullPointerException("Filename can not be null");
- // Calculate the extension of the file
+ // Calculates the extension of the file
int dotIndex = fileName.indexOf(".");
while (dotIndex >= 0 && fileName.indexOf(".",dotIndex+1) >= 0)
dotIndex = fileName.indexOf(".",dotIndex+1);
@@ -257,12 +270,13 @@ public class FileTypeResolver {
return DEFAULT_MIME_TYPE;
}
- /** Gets the descriptive icon representing file, based on the filename.
+ /**
+ * Gets the descriptive icon representing file, based on the filename.
* First the mime-type for the given filename is resolved, and then the
* corresponding icon is fetched from the internal icon storage. If it
* is not found the default icon is returned.
*
- * @param fileName name of the file whose icon is requested
+ * @param fileName the name of the file whose icon is requested.
* @return the icon corresponding to the given file
*/
public static Resource getIcon(String fileName) {
@@ -276,12 +290,13 @@ public class FileTypeResolver {
return DEFAULT_ICON;
}
- /** Gets the descriptive icon representing a file. First the mime-type
+ /**
+ * Gets the descriptive icon representing a file. First the mime-type
* for the given file name is resolved, and then the corresponding
* icon is fetched from the internal icon storage. If it is not found
* the default icon is returned.
*
- * @param file the file whose icon is requested
+ * @param file the file whose icon is requested.
* @return the icon corresponding to the given file
*/
public static Resource getIcon(File file) {
@@ -295,15 +310,16 @@ public class FileTypeResolver {
return DEFAULT_ICON;
}
- /** Gets the mime-type for a file. Currently the returned file type is
+ /**
+ * Gets the mime-type for a file. Currently the returned file type is
* resolved by the filename extension only.
*
- * @param file the file whose mime-type is requested
+ * @param file the file whose mime-type is requested.
* @return the files mime-type String
*/
public static String getMIMEType(File file) {
- // Check for nulls
+ // Checks for nulls
if (file == null)
throw new NullPointerException("File can not be null");
@@ -317,28 +333,31 @@ public class FileTypeResolver {
return getMIMEType(file.getName());
}
- /** Adds a mime-type mapping for the given filename extension. If
+ /**
+ * Adds a mime-type mapping for the given filename extension. If
* the extension is already in the internal mapping it is overwritten.
*
* @param extension the filename extension to be associated with
- * MIMEType
- * @param MIMEType the new mime-type for extension
+ * MIMEType
.
+ * @param MIMEType the new mime-type for extension
.
*/
public static void addExtension(String extension, String MIMEType) {
extToMIMEMap.put(extension, MIMEType);
}
- /** Adds a icon for the given mime-type. If the mime-type also has a
+ /**
+ * Adds a icon for the given mime-type. If the mime-type also has a
* corresponding icon, it is replaced with the new icon.
*
- * @param MIMEType the mime-type whose icon is to be changed
- * @param icon the new icon to be associated with MIMEType
+ * @param MIMEType the mime-type whose icon is to be changed.
+ * @param icon the new icon to be associated with MIMEType
.
*/
public static void addIcon(String MIMEType, Resource icon) {
MIMEToIconMap.put(MIMEType, icon);
}
- /** Gets the internal file extension to mime-type mapping.
+ /**
+ * Gets the internal file extension to mime-type mapping.
*
* @return unmodifiable map containing the current file extension to
* mime-type mapping
@@ -347,7 +366,8 @@ public class FileTypeResolver {
return Collections.unmodifiableMap(extToMIMEMap);
}
- /** Gets the internal mime-type to icon mapping.
+ /**
+ * Gets the internal mime-type to icon mapping.
*
* @return unmodifiable map containing the current mime-type to icon
* mapping
diff --git a/src/com/itmill/toolkit/service/License.java b/src/com/itmill/toolkit/service/License.java
index 61ceea2ff5..3be858666c 100644
--- a/src/com/itmill/toolkit/service/License.java
+++ b/src/com/itmill/toolkit/service/License.java
@@ -59,7 +59,9 @@ import org.xml.sax.SAXException;
public class License {
- /** IT Mill License Manager certificate */
+ /**
+ * IT Mill License Manager certificate.
+ */
private static String certificate = "-----BEGIN CERTIFICATE-----\n"
+ "MIIDJjCCAuQCBEVqxNwwCwYHKoZIzjgEAwUAMHkxCzAJBgNVBAYTAkZJMRAwDgYDVQQIEwdVbmtu\n"
+ "b3duMQ4wDAYDVQQHEwVUdXJrdTEUMBIGA1UEChMLSVQgTWlsbCBMdGQxEDAOBgNVBAsTB1Vua25v\n"
@@ -77,14 +79,18 @@ public class License {
+ "LwAkKye6dzALBgcqhkjOOAQDBQADLwAwLAIUDgvWt7ItRyZfpWNEeJ0P9yaxOwoCFC21LRtwLi1t\n"
+ "c+yomHtX+mpxF7VO\n" + "-----END CERTIFICATE-----\n";
- /** License XML Document */
+ /**
+ * License XML Document.
+ */
private Document licenseXML = null;
- /** The signature has already been checked and is valid */
+ /**
+ * The signature has already been checked and is valid.
+ */
private boolean signatureIsValid = false;
/**
- * Read the license-file from input stream.
+ * Reads the license-file from input stream.
*
* License file can only ne read once, after it has been read it stays.
*
@@ -139,7 +145,18 @@ public class License {
return "true".equalsIgnoreCase(print);
}
-
+ /**
+ * Gets the description for this license.
+ * @return
+ * the description.
+ * @throws LicenseFileHasNotBeenRead
+ * if the license file has not been read.
+ * @throws InvalidLicenseFile
+ * if the license file is not of correct XML format.
+ * @throws LicenseSignatureIsInvalid
+ * if the license file has been changed or signature is
+ * otherwise invalid.
+ */
public String getDescription() throws LicenseFileHasNotBeenRead,
InvalidLicenseFile, LicenseSignatureIsInvalid {
@@ -220,7 +237,7 @@ public class License {
}
/**
- * Check if the license valid for given usage?
+ * Checks if the license valid for given usage?
*
* Checks that the license is valid for specified usage. Throws an exception
* if there is something wrong with the license or use.
@@ -495,14 +512,24 @@ public class License {
return null;
return name;
}
-
+
+ /**
+ * Gets the purpose for this license.
+ * @return the purpose.
+ */
private String getPurpose() {
NodeList purposeL = licenseXML.getElementsByTagName("purpose");
if (purposeL == null || purposeL.getLength() == 0)
return null;
return getTextContent(purposeL.item(0));
}
-
+
+ /**
+ * Gets the license number for this license.
+ * @return the license number of this license, or null
if not set.
+ * @throws InvalidLicenseFile
+ * if the license file is not of correct XML format.
+ */
private String getLicenseNumber() throws InvalidLicenseFile {
Element lic = (Element) licenseXML.getElementsByTagName("license")
.item(0);
@@ -600,7 +627,18 @@ public class License {
return base64_decode(base64);
}
-
+
+ /**
+ * Returns whether the signature is valid or not.
+ * @return true
if the signature is valid otherwise false
.
+ * @throws InvalidLicenseFile
+ * if the license file is not of correct XML format.
+ * @throws LicenseFileHasNotBeenRead
+ * if the license file has not been read.
+ * @throws LicenseSignatureIsInvalid
+ * if the license file has been changed or signature is
+ * otherwise invalid.
+ */
private boolean isSignatureValid() throws InvalidLicenseFile,
LicenseFileHasNotBeenRead, LicenseSignatureIsInvalid {
@@ -712,10 +750,14 @@ public class License {
}
/* ****** BASE64 implementation created by Robert Harder ****** */
- /** The equals sign (=) as a byte. */
+ /**
+ * The equals sign (=) as a byte.
+ */
private final static byte Base64_EQUALS_SIGN = (byte) '=';
- /** Preferred encoding. */
+ /**
+ * Preferred encoding.
+ */
private final static String Base64_PREFERRED_ENCODING = "UTF-8";
/**
@@ -765,22 +807,23 @@ public class License {
* Decodes four bytes from array source and writes the resulting
* bytes (up to three of them) to destination. The source and
* destination arrays can be manipulated anywhere along their length by
- * specifying srcOffset and destOffset. This method
- * does not check to make sure your arrays are large enough to accomodate
- * srcOffset + 4 for the source array or
+ * specifying srcOffset and destOffset.
+ * + * This method does not check to make sure your arrays are large enough + * to accomodate srcOffset + 4 for the source array or * destOffset + 3 for the destination array. This * method returns the actual number of bytes that were converted from the * Base64 encoding. - * + *
* * @param source - * the array to convert + * the array to convert. * @param srcOffset - * the index where conversion begins + * the index where conversion begins. * @param destination - * the array to hold the conversion + * the array to hold the conversion. * @param destOffset - * the index where output will be put + * the index where output will be put. * @return the number of decoded bytes converted * @since 1.3 */ @@ -855,11 +898,11 @@ public class License { * features. * * @param source - * The Base64 encoded data + * the Base64 encoded data. * @param off - * The offset of where to begin decoding + * the offset of where to begin decoding. * @param len - * The length of characters to decode + * the length of characters to decode. * @return decoded data * @since 1.3 */ @@ -912,7 +955,7 @@ public class License { * gzip-compressed data and decompressing it. * * @param s - * the string to decode + * the string to decode. * @return the decoded data * @since 1.4 */ diff --git a/src/com/itmill/toolkit/terminal/ApplicationResource.java b/src/com/itmill/toolkit/terminal/ApplicationResource.java index 2307b1e58f..22f286ef66 100644 --- a/src/com/itmill/toolkit/terminal/ApplicationResource.java +++ b/src/com/itmill/toolkit/terminal/ApplicationResource.java @@ -30,46 +30,63 @@ package com.itmill.toolkit.terminal; import com.itmill.toolkit.Application; -/** This interface must be implemented by classes wishing to provide Application resources. - * - * Application resources are a set of named resources (pictures, sounds, etc) associated +/** + * This interface must be implemented by classes wishing to provide Application resources. + *
+ * ApplicationResource
are a set of named resources (pictures, sounds, etc) associated
* with some specific application. Having named application resources provides a convenient
* method for having inter-theme common resources for an application.
- *
+ *
This gives the adapter the possibility cache streams sent to the + *
+ * This gives the adapter the possibility cache streams sent to the * client. The caching may be made in adapter or at the client if the - * client supports caching. Default is DEFAULT_CACHETIME.
+ * client supports caching. Default isDEFAULT_CACHETIME
.
+ *
*
* @return Cache time in milliseconds
*/
public long getCacheTime();
- /** Get the size of the download buffer used for this resource.
+ /**
+ * Gets the size of the download buffer used for this resource.
*
- * If the buffer size is 0, the buffer size is decided by the - * terminal adapter. The default value is 0.
+ *+ * If the buffer size is 0, the buffer size is decided by the + * terminal adapter. The default value is 0. + *
* - * @return int The size of the buffer in bytes. + * @return int + * the size of the buffer in bytes. */ public int getBufferSize(); diff --git a/src/com/itmill/toolkit/terminal/ClassResource.java b/src/com/itmill/toolkit/terminal/ClassResource.java index dd71c36739..fece5b75df 100644 --- a/src/com/itmill/toolkit/terminal/ClassResource.java +++ b/src/com/itmill/toolkit/terminal/ClassResource.java @@ -31,10 +31,11 @@ package com.itmill.toolkit.terminal; import com.itmill.toolkit.Application; import com.itmill.toolkit.service.FileTypeResolver; -/** Class resource is a named resource accessed with the class loader. +/** + *ClassResource
is a named resource accessed with the class loader.
*
- * This can be used to access resources such as icons, files, etc.
- * @see java.lang.Class#getResource(java.lang.String)
+ * This can be used to access resources such as icons, files, etc.
+ * @see java.lang.Class#getResource(java.lang.String)
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -42,26 +43,37 @@ import com.itmill.toolkit.service.FileTypeResolver;
*/
public class ClassResource implements ApplicationResource {
- /** Default buffer size for this stream resource */
+ /**
+ * Default buffer size for this stream resource.
+ */
private int bufferSize = 0;
- /** Default cache time for this stream resource */
+ /**
+ * Default cache time for this stream resource.
+ */
private long cacheTime = DEFAULT_CACHETIME;
- /** Associated class used for indetifying the source of the resource */
+ /**
+ * Associated class used for indetifying the source of the resource.
+ */
private Class associatedClass;
- /** Name of the resource is relative to the associated class */
+ /**
+ * Name of the resource is relative to the associated class.
+ */
private String resourceName;
- /** Application used for serving the class */
+ /**
+ * Application used for serving the class.
+ */
private Application application;
- /** Create new application resource instance.
+ /**
+ * Creates new application resource instance.
* The resource id is relative to the location of the application class.
*
- * @param resourceName Unique identifier of the resource within the application.
- * @param application The application this resource will be added to.
+ * @param resourceName the Unique identifier of the resource within the application.
+ * @param application the application this resource will be added to.
* */
public ClassResource(String resourceName, Application application) {
this.associatedClass = application.getClass();
@@ -72,12 +84,13 @@ public class ClassResource implements ApplicationResource {
application.addResource(this);
}
- /** Create new application resource instance.
+ /**
+ * Creates new application resource instance.
*
- * @param associatedClass The class of the which the resource is associated.
- * @param resourceName Unique identifier of the resource within the application.
- * @param application The application this resource will be added to.
- * */
+ * @param associatedClass the class of the which the resource is associated.
+ * @param resourceName the Unique identifier of the resource within the application.
+ * @param application the application this resource will be added to.
+ */
public ClassResource(
Class associatedClass,
String resourceName,
@@ -89,15 +102,25 @@ public class ClassResource implements ApplicationResource {
throw new NullPointerException();
application.addResource(this);
}
-
+ /**
+ * Gets the MIME type of this resource.
+ * @see com.itmill.toolkit.terminal.Resource#getMIMEType()
+ */
public String getMIMEType() {
return FileTypeResolver.getMIMEType(this.resourceName);
}
-
+ /**
+ * Gets the application of this resource.
+ * @see com.itmill.toolkit.terminal.ApplicationResource#getApplication()
+ */
public Application getApplication() {
return application;
}
-
+ /**
+ * Gets the virtual filename for this resource.
+ * @return the file name associated to this resource.
+ * @see com.itmill.toolkit.terminal.ApplicationResource#getFilename()
+ */
public String getFilename() {
int index = 0;
int next = 0;
@@ -106,7 +129,10 @@ public class ClassResource implements ApplicationResource {
index = next + 1;
return resourceName.substring(index);
}
-
+ /**
+ * Gets resource as stream.
+ * @see com.itmill.toolkit.terminal.ApplicationResource#getStream()
+ */
public DownloadStream getStream() {
DownloadStream ds = new DownloadStream(
associatedClass.getResourceAsStream(resourceName),
@@ -122,8 +148,9 @@ public class ClassResource implements ApplicationResource {
return bufferSize;
}
- /** Set the size of the download buffer used for this resource.
- * @param bufferSize The size of the buffer in bytes.
+ /**
+ * Sets the size of the download buffer used for this resource.
+ * @param bufferSize the size of the buffer in bytes.
*/
public void setBufferSize(int bufferSize) {
this.bufferSize = bufferSize;
@@ -134,14 +161,17 @@ public class ClassResource implements ApplicationResource {
return cacheTime;
}
- /** Set lenght of cache expiration time.
+ /**
+ * Sets the length of cache expiration time.
*
- * This gives the adapter the possibility cache streams sent to the + *
+ * This gives the adapter the possibility cache streams sent to the * client. The caching may be made in adapter or at the client if the * client supports caching. Zero or negavive value disbales the - * caching of this stream.
+ * caching of this stream. + * * - * @param cacheTime The cache time in milliseconds. + * @param cacheTime the cache time in milliseconds. * */ public void setCacheTime(long cacheTime) { diff --git a/src/com/itmill/toolkit/terminal/CompositeErrorMessage.java b/src/com/itmill/toolkit/terminal/CompositeErrorMessage.java index 8ef96c982c..778df1a41e 100644 --- a/src/com/itmill/toolkit/terminal/CompositeErrorMessage.java +++ b/src/com/itmill/toolkit/terminal/CompositeErrorMessage.java @@ -33,7 +33,8 @@ import java.util.Collection; import java.util.Iterator; import java.util.List; -/** Class for combining multiple error messages together. +/** + * Class for combining multiple error messages together. * * @author IT Mill Ltd * @version @VERSION@ @@ -41,19 +42,22 @@ import java.util.List; */ public class CompositeErrorMessage implements ErrorMessage { - /** Array of all the errors */ + /** + * Array of all the errors. + */ private List errors; - /** Level of the error */ + /** + * Level of the error. + */ private int level; - /** Constructor for CompositeErrorMessage. + /** + * Constructor for CompositeErrorMessage. * - * @param errorMessages Array of error messages that are listed togeter. + * @param errorMessages the Array of error messages that are listed togeter. * Nulls are ignored, but at least one message is required. - * @throws NullPointerException if errorMessages is null. - * * @throws IllegalArgumentException if the array was empty. - */ + */ public CompositeErrorMessage(ErrorMessage[] errorMessages) { errors = new ArrayList(errorMessages.length); level = Integer.MIN_VALUE; @@ -67,11 +71,10 @@ public class CompositeErrorMessage implements ErrorMessage { } - /** Constructor for CompositeErrorMessage. - * @param errorMessages Collection of error messages that are listed + /** + * Constructor for CompositeErrorMessage. + * @param errorMessages the Collection of error messages that are listed * togeter. At least one message is required. - * @throws NullPointerException if the collection is null. - * @throws IllegalArgumentException if the collection was empty. */ public CompositeErrorMessage(Collection errorMessages) { errors = new ArrayList(errorMessages.size()); @@ -85,16 +88,18 @@ public class CompositeErrorMessage implements ErrorMessage { throw new IllegalArgumentException("Composite error message must have at least one error"); } - /** The error level is the largest error level in + /** + * The error level is the largest error level in * @see com.itmill.toolkit.terminal.ErrorMessage#getErrorLevel() */ public final int getErrorLevel() { return level; } - /** Add a error message into this composite message. - * Updates the level field. - * @param error The error message to be added. Duplicate errors are ignored. + /** + * Adds a error message into this composite message. + * Updates the level field. + * @param error the error message to be added. Duplicate errors are ignored. */ private void addErrorMessage(ErrorMessage error) { if (error != null && !errors.contains(error)) { @@ -105,11 +110,17 @@ public class CompositeErrorMessage implements ErrorMessage { } } - /** Get Error Iterator. */ + /** + * Gets Error Iterator. + * @return the error iterator. + */ public Iterator iterator() { return errors.iterator(); } - + + /** + * @see com.itmill.toolkit.terminal.Paintable#paint(com.itmill.toolkit.terminal.PaintTarget) + */ public void paint(PaintTarget target) throws PaintException { if (errors.size() == 1) @@ -153,7 +164,8 @@ public class CompositeErrorMessage implements ErrorMessage { public void requestRepaintRequests() { } - /** Returns a comma separated list of the error messages. + /** + * Returns a comma separated list of the error messages. * @return String, comma separated list of error messages. */ public String toString() { diff --git a/src/com/itmill/toolkit/terminal/DownloadStream.java b/src/com/itmill/toolkit/terminal/DownloadStream.java index 74473ff4db..c4b481e70e 100644 --- a/src/com/itmill/toolkit/terminal/DownloadStream.java +++ b/src/com/itmill/toolkit/terminal/DownloadStream.java @@ -33,7 +33,8 @@ import java.util.HashMap; import java.util.Iterator; import java.util.Map; -/** Downloadable stream. +/** + * Downloadable stream. * * @author IT Mill Ltd. * @version @VERSION@ @@ -41,10 +42,14 @@ import java.util.Map; */ public class DownloadStream { - /** Maximum cache time. */ + /** + * Maximum cache time. + */ public static final long MAX_CACHETIME = Long.MAX_VALUE; - /** Default cache time. */ + /** + * Default cache time. + */ public static final long DEFAULT_CACHETIME = 1000*60*60*24; private InputStream stream; @@ -54,7 +59,9 @@ public class DownloadStream { private long cacheTime = DEFAULT_CACHETIME; private int bufferSize = 0; - /** Creates a new instance of DownloadStream */ + /** + * Creates a new instance of DownloadStream. + */ public DownloadStream( InputStream stream, String contentType, @@ -64,57 +71,64 @@ public class DownloadStream { setFileName(fileName); } - /** Get downloadable stream. + /** + * Gets downloadable stream. * @return output stream. */ public InputStream getStream() { return this.stream; } - /** Sets the stream. + /** + * Sets the stream. * @param stream The stream to set */ public void setStream(InputStream stream) { this.stream = stream; } - /** Get stream content type. + /** + * Gets stream content type. * @return type of the stream content. */ public String getContentType() { return this.contentType; } - /** Set stream content type. - * @param contentType The contentType to set + /** + * Sets stream content type. + * @param contentType the contentType to set */ public void setContentType(String contentType) { this.contentType = contentType; } - /** Returns the file name. - * @return The name of the file. + /** + * Returns the file name. + * @return the name of the file. */ public String getFileName() { return fileName; } - /** Sets the file name. - * @param fileName The file name to set + /** + * Sets the file name. + * @param fileName the file name to set. */ public void setFileName(String fileName) { this.fileName = fileName; } - /** Set a paramater for download stream. - * Parameters are optional information about the downloadable stream - * and their meaning depends on the used adapter. For example in - * WebAdapter they are interpreted as HTTP response headers. + /** + * Sets a paramater for download stream. + * Parameters are optional information about the downloadable stream + * and their meaning depends on the used adapter. For example in + * WebAdapter they are interpreted as HTTP response headers. * - * If the parameters by this name exists, the old value is replaced. + * If the parameters by this name exists, the old value is replaced. * - * @param name Name of the parameter to set. - * @param value Value of the parameter to set. + * @param name the Name of the parameter to set. + * @param value the Value of the parameter to set. */ public void setParameter(String name, String value) { if (this.params == null) { @@ -123,12 +137,13 @@ public class DownloadStream { this.params.put(name, value); } - /** Get a paramater for download stream. - * Parameters are optional information about the downloadable stream - * and their meaning depends on the used adapter. For example in - * WebAdapter they are interpreted as HTTP response headers. - * @param name Name of the parameter to set. - * @return Value of the parameter or null if the parameter does not exist. + /** + * Gets a paramater for download stream. + * Parameters are optional information about the downloadable stream + * and their meaning depends on the used adapter. For example in + * WebAdapter they are interpreted as HTTP response headers. + * @param name the Name of the parameter to set. + * @return Value of the parameter or null if the parameter does not exist. */ public String getParameter(String name) { if (this.params != null) @@ -136,8 +151,9 @@ public class DownloadStream { return null; } - /** Get the names of the parameters. - * @return Iteraror of names or null if no parameters are set. + /** + * Gets the names of the parameters. + * @return Iterator of names or null if no parameters are set. */ public Iterator getParameterNames() { if (this.params != null) @@ -145,35 +161,39 @@ public class DownloadStream { return null; } - /** Get lenght of cache expiration time. - * This gives the adapter the possibility cache streams sent to the client. - * The caching may be made in adapter or at the client if the client supports - * caching. Default is DEFAULT_CACHETIME. + /** + * Gets length of cache expiration time. + * This gives the adapter the possibility cache streams sent to the client. + * The caching may be made in adapter or at the client if the client supports + * caching. Default isDEFAULT_CACHETIME
.
* @return Cache time in milliseconds
*/
public long getCacheTime() {
return cacheTime;
}
- /** Set lenght of cache expiration time.
- * This gives the adapter the possibility cache streams sent to the client.
- * The caching may be made in adapter or at the client if the client supports
- * caching. Zero or negavive value disbales the caching of this stream.
- * @param cacheTime The cache time in milliseconds.
+ /**
+ * Sets length of cache expiration time.
+ * This gives the adapter the possibility cache streams sent to the client.
+ * The caching may be made in adapter or at the client if the client supports
+ * caching. Zero or negavive value disbales the caching of this stream.
+ * @param cacheTime the cache time in milliseconds.
*/
public void setCacheTime(long cacheTime) {
this.cacheTime = cacheTime;
}
- /** Get the size of the download buffer.
+ /**
+ * Gets the size of the download buffer.
* @return int The size of the buffer in bytes.
*/
public int getBufferSize() {
return bufferSize;
}
- /** Set the size of the download buffer.
- * @param bufferSize The size of the buffer in bytes.
+ /**
+ * Sets the size of the download buffer.
+ * @param bufferSize the size of the buffer in bytes.
*/
public void setBufferSize(int bufferSize) {
this.bufferSize = bufferSize;
diff --git a/src/com/itmill/toolkit/terminal/ErrorMessage.java b/src/com/itmill/toolkit/terminal/ErrorMessage.java
index c6a6463e6b..5e0d52f296 100644
--- a/src/com/itmill/toolkit/terminal/ErrorMessage.java
+++ b/src/com/itmill/toolkit/terminal/ErrorMessage.java
@@ -28,7 +28,8 @@
package com.itmill.toolkit.terminal;
-/** Interface for rendering error messages to terminal. All the visible errors
+/**
+ * Interface for rendering error messages to terminal. All the visible errors
* shown to user must implement this interface.
*
* @author IT Mill Ltd.
@@ -37,42 +38,56 @@ package com.itmill.toolkit.terminal;
*/
public interface ErrorMessage extends Paintable {
- /** Error code for system errors and bugs. */
+ /**
+ * Error code for system errors and bugs.
+ */
public static final int SYSTEMERROR = 5000;
- /** Error code for critical error messages. */
+ /**
+ * Error code for critical error messages.
+ */
public static final int CRITICAL = 4000;
- /** Error code for regular error messages. */
+ /**
+ * Error code for regular error messages.
+ */
public static final int ERROR = 3000;
- /** Error code for warning messages. */
+ /**
+ * Error code for warning messages.
+ */
public static final int WARNING = 2000;
- /** Error code for informational messages. */
+ /**
+ * Error code for informational messages.
+ */
public static final int INFORMATION = 1000;
- /** Gets the errors level.
+ /**
+ * Gets the errors level.
*
- * @return the level of error as an integer.
+ * @return the level of error as an integer.
*/
public int getErrorLevel();
- /** Error messages are inmodifiable and thus listeners are not needed. This
+ /**
+ * Error messages are inmodifiable and thus listeners are not needed. This
* method should be implemented as empty.
- *
+ * @param listener the listener to be added.
* @see com.itmill.toolkit.terminal.Paintable#addListener(Paintable.RepaintRequestListener)
*/
public void addListener(RepaintRequestListener listener);
- /** Error messages are inmodifiable and thus listeners are not needed. This
+ /**
+ * Error messages are inmodifiable and thus listeners are not needed. This
* method should be implemented as empty.
- *
+ * @param listener the listener to be removed.
* @see com.itmill.toolkit.terminal.Paintable#removeListener(Paintable.RepaintRequestListener)
*/
public void removeListener(RepaintRequestListener listener);
- /** Error messages are inmodifiable and thus listeners are not needed. This
+ /**
+ * Error messages are inmodifiable and thus listeners are not needed. This
* method should be implemented as empty.
*
* @see com.itmill.toolkit.terminal.Paintable#requestRepaint()
diff --git a/src/com/itmill/toolkit/terminal/ExternalResource.java b/src/com/itmill/toolkit/terminal/ExternalResource.java
index 2c6b95cc64..6b3df1b35a 100644
--- a/src/com/itmill/toolkit/terminal/ExternalResource.java
+++ b/src/com/itmill/toolkit/terminal/ExternalResource.java
@@ -32,7 +32,8 @@ import java.net.URL;
import com.itmill.toolkit.service.FileTypeResolver;
-/** External resource implements source for resources fetched from
+/**
+ * ExternalResource
implements source for resources fetched from
* location specified by URL:s. The resources are fetched directly by the
* client terminal and are not fetched trough the terminal adapter.
*
@@ -42,12 +43,16 @@ import com.itmill.toolkit.service.FileTypeResolver;
*/
public class ExternalResource implements Resource {
- /** Url of the download */
+ /**
+ * Url of the download.
+ */
private String sourceURL = null;
- /** Create new download component for downloading directly from given URL.
- * */
+ /**
+ * Creates new download component for downloading directly from given URL.
+ * @param sourceURL the source URL.
+ */
public ExternalResource(URL sourceURL) {
if (sourceURL == null)
throw new RuntimeException("Source must be non-null");
@@ -55,8 +60,10 @@ public class ExternalResource implements Resource {
this.sourceURL = sourceURL.toString();
}
- /** Create new download component for downloading directly from given URL.
- * */
+ /**
+ * Creates new download component for downloading directly from given URL.
+ * @param sourceURL the source URL.
+ */
public ExternalResource(String sourceURL) {
if (sourceURL == null)
throw new RuntimeException("Source must be non-null");
@@ -64,11 +71,18 @@ public class ExternalResource implements Resource {
this.sourceURL = sourceURL.toString();
}
- /** Get the URL of the external resource */
+ /**
+ * Gets the URL of the external resource.
+ * @return the URL of the external resource.
+ */
public String getURL() {
return sourceURL;
}
+ /**
+ * Gets the MIME type of the resource.
+ * @see com.itmill.toolkit.terminal.Resource#getMIMEType()
+ */
public String getMIMEType() {
return FileTypeResolver.getMIMEType(getURL().toString());
}
diff --git a/src/com/itmill/toolkit/terminal/FileResource.java b/src/com/itmill/toolkit/terminal/FileResource.java
index dcc06cbed5..351edb7377 100644
--- a/src/com/itmill/toolkit/terminal/FileResource.java
+++ b/src/com/itmill/toolkit/terminal/FileResource.java
@@ -35,8 +35,9 @@ import java.io.FileNotFoundException;
import com.itmill.toolkit.Application;
import com.itmill.toolkit.service.FileTypeResolver;
-/** File resources are files or directories on local filesystem. The files and directories
- * are served trough URI:s to the client terminal and thus must be registered to an
+/**
+ * FileResources
are files or directories on local filesystem. The files and directories
+ * are served through URI:s to the client terminal and thus must be registered to an
* URI context before they can be used. The resource is automatically registered
* to the application when it is created.
*
@@ -46,19 +47,28 @@ import com.itmill.toolkit.service.FileTypeResolver;
*/
public class FileResource implements ApplicationResource {
- /** Default buffer size for this stream resource */
+ /**
+ * Default buffer size for this stream resource.
+ */
private int bufferSize = 0;
- /** File where the downloaded content is fetched from. */
+ /**
+ * File where the downloaded content is fetched from.
+ */
private File sourceFile;
- /** Application */
+ /**
+ * Application.
+ */
private Application application;
- /** Default cache time for this stream resource */
+ /**
+ * Default cache time for this stream resource.
+ */
private long cacheTime = DownloadStream.DEFAULT_CACHETIME;
- /** Create new file resource for providing given file for
+ /**
+ * Creates new file resource for providing given file for
* client terminals.
*/
public FileResource(File sourceFile, Application application) {
@@ -66,7 +76,11 @@ public class FileResource implements ApplicationResource {
setSourceFile(sourceFile);
application.addResource(this);
}
-
+
+ /**
+ * Gets the resource as stream.
+ * @see com.itmill.toolkit.terminal.ApplicationResource#getStream()
+ */
public DownloadStream getStream() {
try {
DownloadStream ds = new DownloadStream(
@@ -81,15 +95,17 @@ public class FileResource implements ApplicationResource {
}
}
- /** Returns the source file.
- * @return File
+ /**
+ * Gets the source file.
+ * @return the source File.
*/
public File getSourceFile() {
return sourceFile;
}
- /** Sets the source file.
- * @param sourceFile The source file to set
+ /**
+ * Sets the source file.
+ * @param sourceFile the source file to set.
*/
public void setSourceFile(File sourceFile) {
this.sourceFile = sourceFile;
@@ -116,21 +132,23 @@ public class FileResource implements ApplicationResource {
return FileTypeResolver.getMIMEType(sourceFile);
}
- /** Get lenght of cache expiration time.
- * This gives the adapter the possibility cache streams sent to the client.
- * The caching may be made in adapter or at the client if the client supports
- * caching. Default is DownloadStream.DEFAULT_CACHETIME.
- * @return Cache time in milliseconds
+ /**
+ * Gets the length of cache expiration time.
+ * This gives the adapter the possibility cache streams sent to the client.
+ * The caching may be made in adapter or at the client if the client supports
+ * caching. Default is DownloadStream.DEFAULT_CACHETIME
.
+ * @return Cache time in milliseconds.
*/
public long getCacheTime() {
return cacheTime;
}
- /** Set lenght of cache expiration time.
- * This gives the adapter the possibility cache streams sent to the client.
- * The caching may be made in adapter or at the client if the client supports
- * caching. Zero or negavive value disbales the caching of this stream.
- * @param cacheTime The cache time in milliseconds.
+ /**
+ * Sets the length of cache expiration time.
+ * This gives the adapter the possibility cache streams sent to the client.
+ * The caching may be made in adapter or at the client if the client supports
+ * caching. Zero or negavive value disbales the caching of this stream.
+ * @param cacheTime the cache time in milliseconds.
*/
public void setCacheTime(long cacheTime) {
this.cacheTime = cacheTime;
@@ -141,8 +159,9 @@ public class FileResource implements ApplicationResource {
return bufferSize;
}
- /** Set the size of the download buffer used for this resource.
- * @param bufferSize The size of the buffer in bytes.
+ /**
+ * Sets the size of the download buffer used for this resource.
+ * @param bufferSize the size of the buffer in bytes.
*/
public void setBufferSize(int bufferSize) {
this.bufferSize = bufferSize;
diff --git a/src/com/itmill/toolkit/terminal/KeyMapper.java b/src/com/itmill/toolkit/terminal/KeyMapper.java
index cc220b630d..871fa10751 100644
--- a/src/com/itmill/toolkit/terminal/KeyMapper.java
+++ b/src/com/itmill/toolkit/terminal/KeyMapper.java
@@ -30,8 +30,9 @@ package com.itmill.toolkit.terminal;
import java.util.Hashtable;
-/** Simple two-way map for generating textual keys for objects and
- * retrieving the objects later with the key.
+/**
+ * KeyMapper
is the simple two-way map for generating textual
+ * keys for objects and retrieving the objects later with the key.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -43,7 +44,10 @@ public class KeyMapper {
private Hashtable objectKeyMap = new Hashtable();
private Hashtable keyObjectMap = new Hashtable();
- /** Get key for an object */
+ /**
+ * Gets key for an object.
+ * @param o the object.
+ */
public String key(Object o) {
if (o == null) return "null";
@@ -60,32 +64,44 @@ public class KeyMapper {
return key;
}
- /** Check if the key belongs to a new id.
+ /**
+ * Checks if the key belongs to a new id.
* Usage of new id:s are specific to components, but for example Select
* component uses newItemId:s for selection of newly added items in
- * allowNewItems
-mode
+ * allowNewItems
-mode.
+ * @param key
+ * @return true
if the key belongs to the new id,otherwise false
.
*/
public boolean isNewIdKey(String key) {
return "NEW".equals(key);
}
- /** Retrieve object with the key*/
+ /**
+ * Retrieves object with the key.
+ * @param key the name with the desired value.
+ * @return the object with the key.
+ */
public Object get(String key) {
return keyObjectMap.get(key);
}
- /** Remove object from the mapper. */
- public void remove(Object o) {
- String key = (String) objectKeyMap.get(o);
+ /**
+ * Removes object from the mapper.
+ * @param removeobj the object to be removed.
+ */
+ public void remove(Object removeobj) {
+ String key = (String) objectKeyMap.get(removeobj);
if (key != null) {
objectKeyMap.remove(key);
- keyObjectMap.remove(o);
+ keyObjectMap.remove(removeobj);
}
}
- /** Remove all objects from the mapper. */
+ /**
+ * Removes all objects from the mapper.
+ */
public void removeAll() {
objectKeyMap.clear();
keyObjectMap.clear();
diff --git a/src/com/itmill/toolkit/terminal/PaintException.java b/src/com/itmill/toolkit/terminal/PaintException.java
index 5f3154aa43..766e964b22 100644
--- a/src/com/itmill/toolkit/terminal/PaintException.java
+++ b/src/com/itmill/toolkit/terminal/PaintException.java
@@ -30,7 +30,8 @@ package com.itmill.toolkit.terminal;
import java.io.IOException;
-/** Paint exepction is trown if painting of a component fails.
+/**
+ * PaintExcepection
is thrown if painting of a component fails.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -43,15 +44,17 @@ public class PaintException extends IOException {
*/
private static final long serialVersionUID = 3762535607221891897L;
- /** Constructs an instance of PaintExecption
with the specified detail message.
+ /**
+ * Constructs an instance of PaintExeception
with the specified detail message.
* @param msg the detail message.
*/
public PaintException(String msg) {
super(msg);
}
- /** Constructs an instance of PaintExecption
from IOException.
- * @param exception The original exception.
+ /**
+ * Constructs an instance of PaintExeception
from IOException.
+ * @param exception the original exception.
*/
public PaintException(IOException exception) {
super(exception.getMessage());
diff --git a/src/com/itmill/toolkit/terminal/PaintTarget.java b/src/com/itmill/toolkit/terminal/PaintTarget.java
index 645ac0a4fd..6202b2c399 100644
--- a/src/com/itmill/toolkit/terminal/PaintTarget.java
+++ b/src/com/itmill/toolkit/terminal/PaintTarget.java
@@ -28,8 +28,9 @@
package com.itmill.toolkit.terminal;
-/** This interface defines the methods for
- * painting XML to the UIDL stream.
+/**
+ * This interface defines the methods for
+ * painting XML to the UIDL stream.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -37,27 +38,33 @@ package com.itmill.toolkit.terminal;
*/
public interface PaintTarget {
- /** Print single XMLsection.
+ /**
+ * Prints single XMLsection.
*
* Prints full XML section. The section data is escaped from XML tags and
* surrounded by XML start and end-tags.
+ * @param sectionTagName the name of the tag.
+ * @param sectionData the scetion data.
+ * @throws PaintException if the paint operation failed.
*/
public void addSection(String sectionTagName, String sectionData)
throws PaintException;
- /** Print element start tag of a paintable section.
+ /**
+ * Prints element start tag of a paintable section.
* Starts a paintable section using the given tag. The PaintTarget may
* implement a caching scheme, that checks the paintable has actually
* changed or can a cached version be used instead. This method should call
* the startTag method.
- *
+ *
* If the Paintable is found in cache and this function returns true it may * omit the content and close the tag, in which case cached content should * be used. - * - * @param paintable The paintable to start - * @param tagName The name of the start tag - * @return true if paintable found in cache, false otherwise. + *
+ * @param paintable the paintable to start. + * @param tag the name of the start tag. + * @returntrue
if paintable found in cache, false
otherwise.
+ * @throws PaintException if the paint operation failed.
* @see #startTag(String)
* @since 3.1
*/
@@ -65,141 +72,175 @@ public interface PaintTarget {
throws PaintException;
- /** Print element start tag.
+ /**
+ * Prints element start tag.
*
* Todo: * Checking of input values ** - * @param tagName The name of the start tag - * + * @param tagName the name of the start tag. + * @throws PaintException if the paint operation failed. */ public void startTag(String tagName) throws PaintException; - /** Print element end tag. + /** + * Prints element end tag. * * If the parent tag is closed before * every child tag is closed an PaintException is raised. * - * @param tag The name of the end tag - * @exception IOException The writing failed due to input/output error + * @param tagName the name of the end tag. + * @throws PaintException if the paint operation failed. */ public void endTag(String tagName) throws PaintException; - /** Adds a boolean attribute to component. - * Atributes must be added before any content is written. + /** + * Adds a boolean attribute to component. + * Atributes must be added before any content is written. * - * @param name Attribute name - * @param value Attribute value - * @return this object + * @param name the Attribute name. + * @param value the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, boolean value) throws PaintException; - /** Adds a integer attribute to component. - * Atributes must be added before any content is written. + /** + * Adds a integer attribute to component. + * Atributes must be added before any content is written. * - * @param name Attribute name - * @param value Attribute value - * @return this object + * @param name the Attribute name. + * @param value the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, int value) throws PaintException; - /** Adds a resource attribute to component. - * Atributes must be added before any content is written. + /** + * Adds a resource attribute to component. + * Atributes must be added before any content is written. * - * @param name Attribute name - * @param value Attribute value - * @return this object + * @param name the Attribute name + * @param value the Attribute value + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, Resource value) throws PaintException; - /** Adds a long attribute to component. - * Atributes must be added before any content is written. + /** + * Adds a long attribute to component. + * Atributes must be added before any content is written. * - * @param name Attribute name - * @param value Attribute value - * @return this object + * @param name the Attribute name. + * @param value the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, long value) throws PaintException; - /** Adds a string attribute to component. - * Atributes must be added before any content is written. + /** + * Adds a string attribute to component. + * Atributes must be added before any content is written. * - * @param name Boolean attribute name - * @param value Boolean attribute value - * @return this object + * @param name the Boolean attribute name. + * @param value the Boolean attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, String value) throws PaintException; - /** Add a string type variable. - * @param owner Listener for variable changes - * @param name Variable name - * @param value Variable initial value - * @return Reference to this. + /** + * Adds a string type variable. + * @param owner the Listener for variable changes. + * @param name the Variable name. + * @param value the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, String value) throws PaintException; - /** Add a int type variable. - * @param owner Listener for variable changes - * @param name Variable name - * @param value Variable initial value - * @return Reference to this. + /** + * Adds a int type variable. + * @param owner the Listener for variable changes. + * @param name the Variable name. + * @param value the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, int value) throws PaintException; - /** Add a boolean type variable. - * @param owner Listener for variable changes - * @param name Variable name - * @param value Variable initial value - * @return Reference to this. + /** + * Adds a boolean type variable. + * @param owner the Listener for variable changes. + * @param name the Variable name. + * @param value the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, boolean value) throws PaintException; - /** Add a string array type variable. - * @param owner Listener for variable changes - * @param name Variable name - * @param value Variable initial value - * @return Reference to this. + /** + * Adds a string array type variable. + * @param owner the Listener for variable changes. + * @param name the Variable name. + * @param value the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, String[] value) throws PaintException; - /** Add a upload stream type variable. - * @param owner Listener for variable changes - * @param name Variable name - * @param value Variable initial value - * @return Reference to this. + /** + * Adds a upload stream type variable. + * @param owner the Listener for variable changes. + * @param name the Variable name. + * + * @throws PaintException if the paint operation failed. */ public void addUploadStreamVariable(VariableOwner owner, String name) throws PaintException; - /** Print single XML section. - * - * Prints full XML section. The section data must be XML and it is - * surrounded by XML start and end-tags. - */ + /** + * Prints single XML section. + *
+ * Prints full XML section. The section data must be XML and it is + * surrounded by XML start and end-tags. + *
+ * @param sectionTagName the tag name. + * @param sectionData the section data to be printed. + * @param namespace the namespace. + * @throws PaintException if the paint operation failed. + */ public void addXMLSection( String sectionTagName, String sectionData, String namespace) throws PaintException; - /** Add UIDL directly. + /** + * Adds UIDL directly. * The UIDL must be valid in accordance with the UIDL.dtd + * @param uidl the UIDL to be added. + * @throws PaintException if the paint operation failed. */ public void addUIDL(java.lang.String uidl) throws PaintException; - /** Add text node. All the contents of the text are XML-escaped. - * @param text Text to add + /** + * Adds text node. All the contents of the text are XML-escaped. + * @param text the Text to add + * @throws PaintException if the paint operation failed. */ void addText(String text) throws PaintException; - /** Add CDATA node to target UIDL-tree. - * @param text Character data to add + /** + * Adds CDATA node to target UIDL-tree. + * @param text the Character data to add + * @throws PaintException if the paint operation failed. * @since 3.1 */ void addCharacterData(String text) throws PaintException; diff --git a/src/com/itmill/toolkit/terminal/Paintable.java b/src/com/itmill/toolkit/terminal/Paintable.java index 2f91a81bdd..65b25e0247 100644 --- a/src/com/itmill/toolkit/terminal/Paintable.java +++ b/src/com/itmill/toolkit/terminal/Paintable.java @@ -30,7 +30,8 @@ package com.itmill.toolkit.terminal; import java.util.EventObject; -/** Interface implemented by all classes that can be painted. +/** + * Interface implemented by all classes that can be painted. * Classes implementing this interface know how to output themselves * to a UIDL stream and that way describing to the terminal how it * should be displayed in the UI. @@ -41,28 +42,33 @@ import java.util.EventObject; */ public interface Paintable extends java.util.EventListener { - /**Paints the paintable into a UIDL stream. This method creates + /** + *
+ * Paints the paintable into a UIDL stream. This method creates * the UIDL sequence describing it and outputs it to the given UIDL - * stream.
+ * stream. + * * - *It's is called when the contents of the component should be + *
+ * It is called when the contents of the component should be * painted in response to the component first being shown or having been - * altered so that its visual representation is changed.
+ * altered so that its visual representation is changed. + * * - * @param target target UIDL stream where the component should paint - * itself to - * @throws PaintException if the paint operation failed - * @throws InvalidUIDLException if incorrect UIDL is writted, and - * the error can be dealt with inside this method call. + * @param target the target UIDL stream where the component should paint + * itself to. + * @throws PaintException if the paint operation failed. */ public void paint(PaintTarget target) throws PaintException; - /** Requests that the paintable should be repainted as soon as possible. + /** + * Requests that the paintable should be repainted as soon as possible. */ public void requestRepaint(); - /** Repaint request event is thrown when the paintable needs to be repainted. - * This is typically done when the paint() method would return dissimilar + /** + * Repaint request event is thrown when the paintable needs to be repainted. + * This is typically done when thepaint
method would return dissimilar
* UIDL from the previous call of the method.
*/
public class RepaintRequestEvent extends EventObject {
@@ -72,15 +78,17 @@ public interface Paintable extends java.util.EventListener {
*/
private static final long serialVersionUID = 3256725095530442805L;
- /** Construct new event.
- * @param source The paintable needing repaint
+ /**
+ * Constructs new event.
+ * @param source the paintable needing repaint.
*/
public RepaintRequestEvent(Paintable source) {
super(source);
}
- /** Get the paintable needing repainting.
- * @return Paintable for which the paint() method will return
+ /**
+ * Gets the paintable needing repainting.
+ * @return Paintable for which the paint
method will return
* dissimilar UIDL from the previous call of the method.
*/
public Paintable getPaintable() {
@@ -88,41 +96,47 @@ public interface Paintable extends java.util.EventListener {
}
}
- /** Listen repaint requests. The repaintRequested() method is called when the
+ /**
+ * Listens repaint requests. The repaintRequested
method is called when the
* paintable needs to be repainted.
- * This is typically done when the paint() method would return dissimilar
+ * This is typically done when the paint
method would return dissimilar
* UIDL from the previous call of the method.
*/
public interface RepaintRequestListener {
- /** Receive repaint request events.
- * @param event The repaint request event specifying the paintable source.
+ /**
+ * Receives repaint request events.
+ * @param event the repaint request event specifying the paintable source.
*/
public void repaintRequested(RepaintRequestEvent event);
}
- /** Add repaint request listener. In order to assure that no repaint requests are
+ /**
+ * Adds repaint request listener. In order to assure that no repaint requests are
* missed, the new repaint listener should paint the paintable right after adding
* itself as listener.
- * @param listener to be added
+ * @param listener the listener to be added.
*/
public void addListener(RepaintRequestListener listener);
- /** Remove repaint request listener.
- * @param listener to be removed
+ /**
+ * Removes repaint request listener.
+ * @param listener the listener to be removed.
*/
public void removeListener(RepaintRequestListener listener);
- /** Request sending of repaint events on any further visible changes.
+ /**
+ * Request sending of repaint events on any further visible changes.
* Normally the paintable only send up to one repaint request
* for listeners after paint as the paintable as the paintable
* assumes that the listeners already know about the repaint need.
* This method resets the assumtion. Paint implicitly does the
* assumtion reset functionality implemented by this method.
- *
+ * * This method is normally used only by the terminals to note * paintables about implicit repaints (painting the component * without actually invoking paint method). + *
*/ public void requestRepaintRequests(); } diff --git a/src/com/itmill/toolkit/terminal/ParameterHandler.java b/src/com/itmill/toolkit/terminal/ParameterHandler.java index f9ff314092..f46c67e0a4 100644 --- a/src/com/itmill/toolkit/terminal/ParameterHandler.java +++ b/src/com/itmill/toolkit/terminal/ParameterHandler.java @@ -30,14 +30,17 @@ package com.itmill.toolkit.terminal; import java.util.Map; -/** Interface implemented by all the classes capable of handling external parameters. +/** + * Interface implemented by all the classes capable of handling external parameters. * - *Some terminals can provide external parameters for application. For example + *
+ * Some terminals can provide external parameters for application. For example * GET and POST parameters are passed to application as external parameters on * Web Adapter. The parameters can be received at any time during the application * lifecycle. All the parameter handlers implementing this interface and registered * to {@link com.itmill.toolkit.ui.Window} receive all the parameters got from - * the terminal in the given window.
+ * the terminal in the given window. + * * * @author IT Mill Ltd. * @version @VERSION@ @@ -45,21 +48,27 @@ import java.util.Map; */ public interface ParameterHandler { - /** Handle parameters. - * - *Handle the given parameters. The parameters are given as inmodifieable + /** + *
+ * Handles the given parameters. The parameters are given as inmodifieable * name to value map. All parameters names are of type: {@link java.lang.String}. - * All the parameter values are arrays of strings.
+ * All the parameter values are arrays of strings. + * * - * @param parameters Inmodifiable name to value[] mapping. + * @param parameters the Inmodifiable name to value[] mapping. * */ public void handleParameters(Map parameters); - /** ParameterHandler error event */ + /** + * ParameterHandler error event. + */ public interface ErrorEvent extends Terminal.ErrorEvent { - /** Get the source ParameterHandler. */ + /** + * Gets the source ParameterHandler. + * @return the source Parameter Handler. + */ public ParameterHandler getParameterHandler(); } diff --git a/src/com/itmill/toolkit/terminal/Resource.java b/src/com/itmill/toolkit/terminal/Resource.java index 66eb23f8bc..74163b8ef5 100644 --- a/src/com/itmill/toolkit/terminal/Resource.java +++ b/src/com/itmill/toolkit/terminal/Resource.java @@ -28,8 +28,9 @@ package com.itmill.toolkit.terminal; -/** Resource provided to the client terminal. Support for actually displaying the resource type - * is left to the terminal. +/** + *Resource
provided to the client terminal. Support for actually
+ * displaying the resource type is left to the terminal.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -37,6 +38,9 @@ package com.itmill.toolkit.terminal;
*/
public interface Resource {
- /** Get the MIME type of the resource. */
+ /**
+ * Gets the MIME type of the resource.
+ * @return the MIME type of the resource.
+ */
public String getMIMEType();
}
diff --git a/src/com/itmill/toolkit/terminal/Scrollable.java b/src/com/itmill/toolkit/terminal/Scrollable.java
index 87ece18c5d..dcc1528e66 100644
--- a/src/com/itmill/toolkit/terminal/Scrollable.java
+++ b/src/com/itmill/toolkit/terminal/Scrollable.java
@@ -28,10 +28,11 @@
package com.itmill.toolkit.terminal;
-/** Scrollable interface.
- *
- * This interface is implemented by all visual objects that can be scrolled. - * The unit of scrolling is pixel.
+/** + *+ * This interface is implemented by all visual objects that can be scrolled. + * The unit of scrolling is pixel. + *
* * @author IT Mill Ltd. * @version @VERSION@ @@ -40,7 +41,8 @@ package com.itmill.toolkit.terminal; public interface Scrollable { - /** Get scroll X offset. + /** + * Gets scroll X offset. * *Scrolling offset is the number of pixels this scrollable has * been scrolled to left.
@@ -49,16 +51,18 @@ public interface Scrollable { */ public int getScrollOffsetX(); - /** Set scroll X offset. + /** + * Sets scroll X offset. * *Scrolling offset is the number of pixels this scrollable has * been scrolled to left.
* - * @param xOffset. + * @param pixelsScrolledLeft the xOffset. */ public void setScrollOffsetX(int pixelsScrolledLeft); - /** Get scroll Y offset. + /** + * Gets scroll Y offset. * *Scrolling offset is the number of pixels this scrollable has * been scrolled to down.
@@ -67,30 +71,33 @@ public interface Scrollable { */ public int getScrollOffsetY(); - /** Set scroll Y offset. + /** + * Sets scroll Y offset. * *Scrolling offset is the number of pixels this scrollable has * been scrolled to down.
* - * @param yOffset. + * @param pixelsScrolledDown the yOffset. */ public void setScrollOffsetY(int pixelsScrolledDown); - /** Is the scrolling enabled. + /** + * Is the scrolling enabled. * *Enabling scrolling allows the user to scroll the scrollable view * interactively
* - * @return True iff the scrolling is allowed. + * @returntrue
if the scrolling is allowed, otherwise false
.
*/
public boolean isScrollable();
- /** Enable or disable scrolling..
+ /**
+ * Enables or disables scrolling..
*
* Enabling scrolling allows the user to scroll the scrollable view * interactively
* - * @param isScrollingEnabled True iff the scrolling is allowed. + * @param isScrollingEnabled true if the scrolling is allowed. */ public void setScrollable(boolean isScrollingEnabled); diff --git a/src/com/itmill/toolkit/terminal/Sizeable.java b/src/com/itmill/toolkit/terminal/Sizeable.java index 92e64d274d..3a191b52f3 100644 --- a/src/com/itmill/toolkit/terminal/Sizeable.java +++ b/src/com/itmill/toolkit/terminal/Sizeable.java @@ -28,9 +28,10 @@ package com.itmill.toolkit.terminal; -/** Interface to be implemented by components wishing to - * display some object that may be dynamically - * resized during runtime. +/** + * Interface to be implemented by components wishing to + * display some object that may be dynamically + * resized during runtime. * * @author IT Mill Ltd. * @version @VERSION@ @@ -38,100 +39,127 @@ package com.itmill.toolkit.terminal; */ public interface Sizeable { - /** Unit code representing pixels. */ + /** + * Unit code representing pixels. + */ public static final int UNITS_PIXELS = 0; - /** Unit code representing points (1/72nd of an inch). */ + /** + * Unit code representing points (1/72nd of an inch). + */ public static final int UNITS_POINTS = 1; - /** Unit code representing picas (12 points). */ + /** + * Unit code representing picas (12 points). + */ public static final int UNITS_PICAS = 2; - /** Unit code representing the font-size of the relevant font. */ + /** + * Unit code representing the font-size of the relevant font. + */ public static final int UNITS_EM = 3; - /** Unit code representing the x-height of the relevant font. */ + /** + * Unit code representing the x-height of the relevant font. + */ public static final int UNITS_EX = 4; - /** Unit code representing millimetres. */ + /** + * Unit code representing millimetres. + */ public static final int UNITS_MM = 5; - /** Unit code representing centimetres. */ + /** + * Unit code representing centimetres. + */ public static final int UNITS_CM = 6; - /** Unit code representing inches. */ + /** + * Unit code representing inches. + */ public static final int UNITS_INCH = 7; - /** Unit code representing in percentage of the containing element - * defined by terminal. + /** + * Unit code representing in percentage of the containing element + * defined by terminal. */ public static final int UNITS_PERCENTAGE = 8; - /** Unit code representing in rows of text. This unit is only applicaple + /** + * Unit code representing in rows of text. This unit is only applicaple * to some components can it's meaning is specified by component implementation. */ public static final int UNITS_ROWS = 9; - /** Textual representations of units symbols. - * Supported units and their symbols are: - *UNITS_PIXELS
: "" (unit is omitted for pixels)UNITS_POINTS
: "pt"UNITS_PICAS
: "pc"UNITS_EM
: "em"UNITS_EX
: "ex"UNITS_MM
: "mm"UNITS_CM
. "cm"UNITS_INCH
: "in"UNITS_PERCENTAGE
: "%"UNITS_ROWS
: "rows"Sizeable.UNIT_SYMBOLS[UNITS_PIXELS]
.
+ /**
+ * Textual representations of units symbols.
+ * Supported units and their symbols are:
+ * UNITS_PIXELS
: "" (unit is omitted for pixels)UNITS_POINTS
: "pt"UNITS_PICAS
: "pc"UNITS_EM
: "em"UNITS_EX
: "ex"UNITS_MM
: "mm"UNITS_CM
. "cm"UNITS_INCH
: "in"UNITS_PERCENTAGE
: "%"UNITS_ROWS
: "rows"Sizeable.UNIT_SYMBOLS[UNITS_PIXELS]
.
*/
public static final String[] UNIT_SYMBOLS =
{ "", "pt", "pc", "em", "ex", "mm", "cm", "in", "%", "rows" };
- /** Get width of the object. Negative number implies unspecified size
+ /**
+ * Gets the width of the object. Negative number implies unspecified size
* (terminal is free to set the size).
* @return width of the object in units specified by widthUnits property.
*/
public int getWidth();
- /** Set width of the object. Negative number implies unspecified size
+ /**
+ * Sets the width of the object. Negative number implies unspecified size
* (terminal is free to set the size).
- * @param width width of the object in units specified by widthUnits property.
+ * @param width the width of the object in units specified by widthUnits property.
*/
public void setWidth(int width);
- /** Get height of the object. Negative number implies unspecified size
+ /**
+ * Gets the height of the object. Negative number implies unspecified size
* (terminal is free to set the size).
* @return height of the object in units specified by heightUnits property.
*/
public int getHeight();
- /** Set height of the object. Negative number implies unspecified size
+ /**
+ * Sets the height of the object. Negative number implies unspecified size
* (terminal is free to set the size).
- * @param height height of the object in units specified by heightUnits property.
+ * @param height the height of the object in units specified by heightUnits property.
*/
public void setHeight(int height);
- /** Get width property units.
+ /**
+ * Gets the width property units.
* @return units used in width property.
*/
public int getWidthUnits();
- /** Set width property units.
- * @param units units used in width property.
+ /**
+ * Sets the width property units.
+ * @param units the units used in width property.
*/
public void setWidthUnits(int units);
- /** Get height property units.
+ /**
+ * Gets the height property units.
* @return units used in height property.
*/
public int getHeightUnits();
- /** Set height property units.
- * @param units units used in height property.
+ /**
+ * Sets the height property units.
+ * @param units the units used in height property.
*/
public void setHeightUnits(int units);
diff --git a/src/com/itmill/toolkit/terminal/StreamResource.java b/src/com/itmill/toolkit/terminal/StreamResource.java
index 8d2a38e004..af0201c0c2 100644
--- a/src/com/itmill/toolkit/terminal/StreamResource.java
+++ b/src/com/itmill/toolkit/terminal/StreamResource.java
@@ -33,35 +33,54 @@ import java.io.InputStream;
import com.itmill.toolkit.Application;
import com.itmill.toolkit.service.FileTypeResolver;
-/** Stream resource is a resource provided to the client directly
+/**
+ * StreamResource
is a resource provided to the client directly
* by the application. The strean resource is fetched from URI
* that is most often in the context of the application or window.
* The resource is automatically registered to window in creation.
+ *
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
*/
public class StreamResource implements ApplicationResource {
- /** Source streamthe downloaded content is fetched from */
+ /**
+ * Source stream the downloaded content is fetched from.
+ */
private StreamSource streamSource = null;
- /** Explicit mime-type */
+ /**
+ * Explicit mime-type.
+ */
private String MIMEType = null;
- /** Filename */
+ /**
+ * Filename.
+ */
private String filename;
- /** Application */
+ /**
+ * Application.
+ */
private Application application;
- /** Default buffer size for this stream resource */
+ /**
+ * Default buffer size for this stream resource.
+ */
private int bufferSize = 0;
- /** Default cache time for this stream resource */
+ /**
+ * Default cache time for this stream resource.
+ */
private long cacheTime = DEFAULT_CACHETIME;
- /** Create new stream resource for downloading from stream. */
+ /**
+ * Creates new stream resource for downloading from stream.
+ * @param streamSource the source Stream.
+ * @param filename the name of the file.
+ * @param application the Application object.
+ */
public StreamResource(
StreamSource streamSource,
String filename,
@@ -75,45 +94,54 @@ public class StreamResource implements ApplicationResource {
application.addResource(this);
}
-
+ /**
+ * @see com.itmill.toolkit.terminal.Resource#getMIMEType()
+ */
public String getMIMEType() {
if (MIMEType != null)
return MIMEType;
return FileTypeResolver.getMIMEType(filename);
}
- /** Set the mime type of the resource */
+ /**
+ * Sets the mime type of the resource.
+ * @param MIMEType the MIME type to be set.
+ */
public void setMIMEType(String MIMEType) {
this.MIMEType = MIMEType;
}
- /** Returns the source for this StreamResource.
- * StreamSource is queried when the resource is about to be streamed
- * to the client.
+ /**
+ * Returns the source for this StreamResource
.
+ * StreamSource is queried when the resource is about to be streamed
+ * to the client.
* @return Source of the StreamResource.
*/
public StreamSource getStreamSource() {
return streamSource;
}
- /** Sets the source for this StreamResource.
- * StreamSource is queried when the resource is about to be streamed
- * to the client.
- * @param streamSource The source to set
+ /**
+ * Sets the source for this StreamResource
.
+ * StreamSource
is queried when the resource is about to be streamed
+ * to the client.
+ * @param streamSource the source to set.
*/
public void setStreamSource(StreamSource streamSource) {
this.streamSource = streamSource;
}
- /** Returns the filename.
- * @return String
+ /**
+ * Gets the filename.
+ * @return the filename.
*/
public String getFilename() {
return filename;
}
- /** Sets the filename.
- * @param filename The filename to set
+ /**
+ * Sets the filename.
+ * @param filename the filename to set.
*/
public void setFilename(String filename) {
this.filename = filename;
@@ -139,15 +167,18 @@ public class StreamResource implements ApplicationResource {
return ds;
}
- /** Interface implemented by the source of a StreamResource.
+ /**
+ * Interface implemented by the source of a StreamResource.
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
*/
public interface StreamSource {
- /** Return new input stream that is used for reading
- * the resource */
+ /**
+ * Returns new input stream that is used for reading
+ * the resource.
+ */
public InputStream getStream();
}
@@ -156,8 +187,9 @@ public class StreamResource implements ApplicationResource {
return bufferSize;
}
- /** Set the size of the download buffer used for this resource.
- * @param bufferSize The size of the buffer in bytes.
+ /**
+ * Sets the size of the download buffer used for this resource.
+ * @param bufferSize the size of the buffer in bytes.
*/
public void setBufferSize(int bufferSize) {
this.bufferSize = bufferSize;
@@ -168,14 +200,15 @@ public class StreamResource implements ApplicationResource {
return cacheTime;
}
- /** Set lenght of cache expiration time.
+ /**
+ * Sets the length of cache expiration time.
*
* This gives the adapter the possibility cache streams sent to the * client. The caching may be made in adapter or at the client if the * client supports caching. Zero or negavive value disbales the * caching of this stream.
* - * @param cacheTime The cache time in milliseconds. + * @param cacheTime the cache time in milliseconds. * */ public void setCacheTime(long cacheTime) { diff --git a/src/com/itmill/toolkit/terminal/SystemError.java b/src/com/itmill/toolkit/terminal/SystemError.java index c6dfe77c49..617bfe43b4 100644 --- a/src/com/itmill/toolkit/terminal/SystemError.java +++ b/src/com/itmill/toolkit/terminal/SystemError.java @@ -31,8 +31,9 @@ package com.itmill.toolkit.terminal; import java.io.PrintWriter; import java.io.StringWriter; -/** System error is a runtime exception caused by error in system. The system - * error can be shown to the user as it implements ErrorMessage interface, +/** + *SystemError
is a runtime exception caused by error in system. The system
+ * error can be shown to the user as it implements ErrorMessage
interface,
* but contains technical information such as stack trace and exception.
*
* @author IT Mill Ltd.
@@ -46,37 +47,48 @@ public class SystemError extends RuntimeException implements ErrorMessage {
*/
private static final long serialVersionUID = 3256445789512675891L;
- /** The cause of the system error. The cause is stored separately as
- * JDK 1.3 does not support causes natively */
+ /**
+ * The cause of the system error. The cause is stored separately as
+ * JDK 1.3 does not support causes natively.
+ */
private Throwable cause = null;
- /** Constructor for SystemError with error message specified.
- * @param message Textual error description.
+ /**
+ * Constructor for SystemError with error message specified.
+ * @param message the Textual error description.
*/
public SystemError(String message) {
super(message);
}
- /** Constructor for SystemError with causing exception and error message.
- * @param message Textual error description.
- * @param cause The throwable causing the system error.
+ /**
+ * Constructor for SystemError with causing exception and error message.
+ * @param message the Textual error description.
+ * @param cause the throwable causing the system error.
*/
public SystemError(String message, Throwable cause) {
super(message);
this.cause = cause;
}
- /** Constructor for SystemError with cause.
- * @param cause The throwable causing the system error.
+ /**
+ * Constructor for SystemError with cause.
+ * @param cause the throwable causing the system error.
*/
public SystemError(Throwable cause) {
this.cause = cause;
}
-
+
+ /**
+ * @see com.itmill.toolkit.terminal.ErrorMessage#getErrorLevel()
+ */
public final int getErrorLevel() {
return ErrorMessage.SYSTEMERROR;
}
-
+
+ /**
+ * @see com.itmill.toolkit.terminal.Paintable#paint(com.itmill.toolkit.terminal.PaintTarget)
+ */
public void paint(PaintTarget target) throws PaintException {
target.startTag("error");
@@ -100,10 +112,14 @@ public class SystemError extends RuntimeException implements ErrorMessage {
}
target.endTag("error");
-
+
}
- /** Get cause for the error */
+ /**
+ * Gets cause for the error.
+ * @return the cause.
+ * @see java.lang.Throwable#getCause()
+ */
public Throwable getCause() {
return cause;
}
diff --git a/src/com/itmill/toolkit/terminal/Terminal.java b/src/com/itmill/toolkit/terminal/Terminal.java
index b9dfd4bb5d..d1ab02239e 100644
--- a/src/com/itmill/toolkit/terminal/Terminal.java
+++ b/src/com/itmill/toolkit/terminal/Terminal.java
@@ -28,7 +28,8 @@
package com.itmill.toolkit.terminal;
-/** Interface for different terminal types.
+/**
+ * Interface for different terminal types.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -37,33 +38,45 @@ package com.itmill.toolkit.terminal;
public interface Terminal {
- /** Get name of the default theme
- * @return Name of the terminal window
+ /**
+ * Gets the name of the default theme.
+ * @return the Name of the terminal window.
*/
public String getDefaultTheme();
- /** Get width of the terminal window in pixels
- * @return Width of the terminal window
+ /**
+ * Gets the width of the terminal window in pixels.
+ * @return the Width of the terminal window.
*/
public int getScreenWidth();
- /** Get height of the terminal window in pixels
- * @return Height of the terminal window
+ /**
+ * Gets the height of the terminal window in pixels.
+ * @return the Height of the terminal window.
*/
public int getScreenHeight();
- /** Terminal error event */
+ /**
+ * Terminal error event.
+ */
public interface ErrorEvent {
- /** Get the contained throwable */
+ /**
+ * Gets the contained throwable.
+ */
public Throwable getThrowable();
}
- /** Terminal error listener interface */
+ /**
+ * Terminal error listener interface.
+ */
public interface ErrorListener {
- /** Invoked when terminal error occurs. */
+ /**
+ * Invoked when terminal error occurs.
+ * @param event the fired event.
+ */
public void terminalError(Terminal.ErrorEvent event);
}
}
diff --git a/src/com/itmill/toolkit/terminal/ThemeResource.java b/src/com/itmill/toolkit/terminal/ThemeResource.java
index 3f1c518bbb..5215ade6ab 100644
--- a/src/com/itmill/toolkit/terminal/ThemeResource.java
+++ b/src/com/itmill/toolkit/terminal/ThemeResource.java
@@ -30,7 +30,8 @@ package com.itmill.toolkit.terminal;
import com.itmill.toolkit.service.FileTypeResolver;
-/** Theme resource is a named theme dependant resource provided and
+/**
+ * ThemeResource
is a named theme dependant resource provided and
* managed by a theme. The actual resource contents are dynamically
* resolved to comply with the used theme by the terminal adapter.
* This is commonly used to provide static images, flash,
@@ -42,10 +43,15 @@ import com.itmill.toolkit.service.FileTypeResolver;
*/
public class ThemeResource implements Resource {
- /** Id of the terminal managed resource. */
+ /**
+ * Id of the terminal managed resource.
+ */
private String resourceID = null;
- /** Create a resource. */
+ /**
+ * Creates a resource.
+ * @param resourceId the Id of the resource.
+ */
public ThemeResource(String resourceId) {
if (resourceId == null)
throw new NullPointerException("Resource ID must not be null");
@@ -59,11 +65,12 @@ public class ThemeResource implements Resource {
this.resourceID = resourceId;
}
- /** Tests if the given object equals this Resource.
+ /**
+ * Tests if the given object equals this Resource.
*
- * @param obj the object to be tested for equality
+ * @param obj the object to be tested for equality.
* @return true
if the given object equals this Icon,
- * false
if not
+ * false
if not.
* @see java.lang.Object#equals(Object)
*/
public boolean equals(Object obj) {
@@ -71,21 +78,31 @@ public class ThemeResource implements Resource {
resourceID.equals(((ThemeResource)obj).resourceID);
}
- /** @see java.lang.Object#hashCode()
+ /**
+ * @see java.lang.Object#hashCode()
*/
public int hashCode() {
return resourceID.hashCode();
}
+ /**
+ * @see java.lang.Object#toString()
+ */
public String toString() {
return resourceID.toString();
}
- /** Get the resource id */
+ /**
+ * Gets the resource id.
+ * @return the resource id.
+ */
public String getResourceId() {
return resourceID;
}
+ /**
+ * @see com.itmill.toolkit.terminal.Resource#getMIMEType()
+ */
public String getMIMEType() {
return FileTypeResolver.getMIMEType(getResourceId());
}
diff --git a/src/com/itmill/toolkit/terminal/URIHandler.java b/src/com/itmill/toolkit/terminal/URIHandler.java
index 77ebea9688..0f709191c4 100644
--- a/src/com/itmill/toolkit/terminal/URIHandler.java
+++ b/src/com/itmill/toolkit/terminal/URIHandler.java
@@ -30,10 +30,13 @@ package com.itmill.toolkit.terminal;
import java.net.URL;
-/** Interface implemented by all the classes capable of handling URI:s.
+/**
+ * Interface implemented by all the classes capable of handling URI:s.
*
- * URI handlers can provide DownloadStream
- * for transferring data for client.
+ * URIHandler
can provide DownloadStream
+ * for transferring data for client.
+ *
UserError
is a controlled error occurred in application. User errors
* are occur in normal usage of the application and guide the user.
*
* @author IT Mill Ltd.
@@ -37,37 +38,51 @@ package com.itmill.toolkit.terminal;
*/
public class UserError implements ErrorMessage {
- /** Content mode, where the error contains only plain text.
+ /**
+ * Content mode, where the error contains only plain text.
*/
public static final int CONTENT_TEXT = 0;
- /** Content mode, where the error contains preformatted text.
+ /**
+ * Content mode, where the error contains preformatted text.
*/
public static final int CONTENT_PREFORMATTED = 1;
- /** Formatted content mode, where the contents is XML restricted to the
+ /**
+ * Formatted content mode, where the contents is XML restricted to the
* UIDL 1.0 formatting markups.
*/
public static final int CONTENT_UIDL = 2;
- /** Content mode */
+ /**
+ * Content mode.
+ */
private int mode = CONTENT_TEXT;
- /** Message in content mode */
+ /**
+ * Message in content mode.
+ */
private String msg;
- /** Error level */
+ /**
+ * Error level.
+ */
private int level = ErrorMessage.ERROR;
- /** Create a textual error message of level ERROR.
+ /**
+ * Creates a textual error message of level ERROR.
*
- * @param textErrorMessage The text of the error message.
+ * @param textErrorMessage the text of the error message.
*/
public UserError(String textErrorMessage) {
this.msg = textErrorMessage;
}
- /** Create error message with level and content mode.
+ /**
+ * Creates error message with level and content mode.
+ * @param message the error message.
+ * @param contentMode the content Mode.
+ * @param errorLevel the level of error.
*/
public UserError(String message, int contentMode, int errorLevel) {
diff --git a/src/com/itmill/toolkit/terminal/VariableOwner.java b/src/com/itmill/toolkit/terminal/VariableOwner.java
index d442557716..a56460c517 100644
--- a/src/com/itmill/toolkit/terminal/VariableOwner.java
+++ b/src/com/itmill/toolkit/terminal/VariableOwner.java
@@ -31,22 +31,29 @@ package com.itmill.toolkit.terminal;
import java.util.Map;
import java.util.Set;
-/** Listener interface for UI variable changes. The user communicates +/** + *
+ * Listener interface for UI variable changes. The user communicates * with the application using the so-called variables. When the user * makes a change using the UI the terminal trasmits the changed variables * to the application, and the components owning those variables may then - * process those changes.
+ * process those changes. + * * - *The variable-owning components can be linked with dependency + *
+ * The variable-owning components can be linked with dependency * relationships. A dependency between two components means that all * variable change events to the depended component will be handled - * before any such events to the depending component.
+ * before any such events to the depending component. + * * - *For example, the commit button for a text field will depend on that + *
+ * For example, the commit button for a text field will depend on that * text field. This is because we want to handle any pending changes the - * user makes to the contents on the text field before before we accept the + * user makes to the contents on the text field before we accept the * click of the commit button which starts processing the text field - * contents.
+ * contents. + * * * @author IT Mill Ltd. * @version @VERSION@ @@ -54,47 +61,53 @@ import java.util.Set; */ public interface VariableOwner { - /** Gets the variable change listeners thisVariableOwner
+ /**
+ * Gets the variable change listeners this VariableOwner
* directly depends on. This list does not contain any indirect
* dependencies, for example, if A depends on B and B depends on C,
* the dependency list of A does not include C.
*
- * @return Set of VariableOwner
s this component directly
+ * @return Set of VariableOwners
this component directly
* depend on, null
if this component does not depend on
* anybody.
*/
public Set getDirectDependencies();
- /** Called when one or more variables handled by the implementing class
+ /**
+ * Called when one or more variables handled by the implementing class
* are changed.
*
- * @param source Source of the variable change. This is the origin of the
+ * @param source the Source of the variable change. This is the origin of the
* event. For example in Web Adapter this is the request.
- * @param variables Mapping from variable names to new variable values
+ * @param variables the Mapping from variable names to new variable values.
*/
public void changeVariables(Object source, Map variables);
- /** Makes this VariableOwner
depend on the given
+ /**
+ * Makes this VariableOwner
depend on the given
* VariableOwner
. This means that any variable change
* events relating to depended
must be sent before any
* such events that relate to this object.
*
- * @param denpended the VariableOwner
component who
- * this component depends on
+ * @param depended the VariableOwner
component who
+ * this component depends on.
*/
public void dependsOn(VariableOwner depended);
- /** Removes the given component from this component's dependency list.
+ /**
+ * Removes the given component from this component's dependency list.
* After the call this component will no longer depend on
* depended
wdepende direct dependency from the component.
* Indirect dependencies are not removed.
*
- * @param denpended the component to be removed from this component's
+ * @param depended the component to be removed from this component's
* dependency list.
*/
public void removeDirectDependency(VariableOwner depended);
- /** Tests if the variable owner is enabled or not. The terminal + /** + *
+ * Tests if the variable owner is enabled or not. The terminal * should not send any variable changes to disabled variable owners. *
* @@ -103,26 +116,35 @@ public interface VariableOwner { */ public boolean isEnabled(); - /**Tests if the variable owner is in immediate mode or not. Being in + /** + *
+ * Tests if the variable owner is in immediate mode or not. Being in * immediate mode means that all variable changes are required to be sent * back from the terminal immediately when they occur. *
* - *Note: VariableOwner
does not include a
+ *
+ * Note: VariableOwner
does not include a
* set- method for the immediateness property. This is because not all
* VariableOwners wish to offer the functionality. Such VariableOwners are
* never in the immediate mode, thus they always return false
- * in {@link #isImmediate()}.
true
if the component is in immediate mode,
- * false
if not
+ * false
if not.
*/
public boolean isImmediate();
- /** VariableOwner error event */
+ /**
+ * VariableOwner error event.
+ */
public interface ErrorEvent extends Terminal.ErrorEvent {
- /** Get the source VariableOwner. */
+ /**
+ * Gets the source VariableOwner.
+ * @return the variable owner.
+ */
public VariableOwner getVariableOwner();
}
diff --git a/src/com/itmill/toolkit/terminal/web/AjaxApplicationManager.java b/src/com/itmill/toolkit/terminal/web/AjaxApplicationManager.java
index bf8bbf9629..2e43005574 100644
--- a/src/com/itmill/toolkit/terminal/web/AjaxApplicationManager.java
+++ b/src/com/itmill/toolkit/terminal/web/AjaxApplicationManager.java
@@ -61,8 +61,9 @@ import com.itmill.toolkit.ui.Component;
import com.itmill.toolkit.ui.FrameWindow;
import com.itmill.toolkit.ui.Window;
-/** Application manager processes changes and paints for single
- * application instance.
+/**
+ * Application manager processes changes and paints for single
+ * application instance.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -94,7 +95,11 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
public AjaxApplicationManager(Application application) {
this.application = application;
}
-
+
+/**
+ *
+ * @return
+ */
private AjaxVariableMap getVariableMap() {
AjaxVariableMap vm = (AjaxVariableMap) applicationToVariableMapMap
.get(application);
@@ -104,18 +109,32 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
return vm;
}
-
+
+/**
+ *
+ *
+ */
public void takeControl() {
application.addListener((Application.WindowAttachListener) this);
application.addListener((Application.WindowDetachListener) this);
}
-
+
+/**
+ *
+ *
+ */
public void releaseControl() {
application.removeListener((Application.WindowAttachListener) this);
application.removeListener((Application.WindowDetachListener) this);
}
-
+
+/**
+ *
+ * @param request the HTTP Request.
+ * @param response the HTTP Response.
+ * @throws IOException if the writing failed due to input/output error.
+ */
public void handleUidlRequest(HttpServletRequest request,
HttpServletResponse response) throws IOException {
@@ -138,35 +157,35 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
Map unhandledParameters = getVariableMap().handleVariables(
request, application);
- // Handle the URI if the application is still running
+ // Handles the URI if the application is still running
if (application.isRunning())
download = handleURI(application, request, response);
// If this is not a download request
if (download == null) {
- // Find the window within the application
+ // Finds the window within the application
Window window = null;
if (application.isRunning())
window = getApplicationWindow(request, application);
- // Handle the unhandled parameters if the application is
+ // Handles the unhandled parameters if the application is
// still running
if (window != null && unhandledParameters != null
&& !unhandledParameters.isEmpty())
window.handleParameters(unhandledParameters);
- // Remove application if it has stopped
+ // Removes application if it has stopped
if (!application.isRunning()) {
endApplication(request, response, application);
return;
}
- // Return if no window found
+ // Returns if no window found
if (window == null)
return;
- // Set the response type
+ // Sets the response type
response.setContentType("application/xml; charset=UTF-8");
paintTarget = new AjaxPaintTarget(
@@ -190,13 +209,13 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
}
- // Paint components
+ // Paints components
Set paintables;
if (repaintAll) {
paintables = new LinkedHashSet();
paintables.add(window);
- // Add all non-native windows
+ // Adds all non-native windows
for (Iterator i=window.getApplication().getWindows().iterator(); i.hasNext();) {
Window w = (Window) i.next();
if (!"native".equals(w.getStyle()) && w != window)
@@ -206,10 +225,10 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
paintables = getDirtyComponents();
if (paintables != null) {
- // Create "working copy" of the current state.
+ // Creates "working copy" of the current state.
List currentPaintables = new ArrayList(paintables);
- // Sort the paintable so that parent windows
+ // Sorts the paintable so that parent windows
// are always painted before child windows
Collections.sort(currentPaintables, new Comparator() {
@@ -304,7 +323,7 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
out.close();
} catch (Throwable e) {
- // Write the error report to client
+ // Writes the error report to client
OutputStreamWriter w = new OutputStreamWriter(out);
PrintWriter err = new PrintWriter(w);
err
@@ -320,14 +339,16 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
/**
- * Get the existing application or create a new one. Get a window within an
+ * Gets the existing application or create a new one. Get a window within an
* application based on the requested URI.
*
* @param request
- * HTTP Request.
+ * the HTTP Request.
* @param application
- * Application to query for window.
+ * the Application to query for window.
* @return Window mathing the given URI or null if not found.
+ * @throws ServletException if an exception has occurred that interferes with the
+ * servlet's normal operation.
*/
private Window getApplicationWindow(HttpServletRequest request,
Application application) throws ServletException {
@@ -365,21 +386,20 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
/**
- * Handle the requested URI. An application can add handlers to do special
+ * Handles the requested URI. An application can add handlers to do special
* processing, when a certain URI is requested. The handlers are invoked
* before any windows URIs are processed and if a DownloadStream is returned
* it is sent to the client.
*
- * @see com.itmill.toolkit.terminal.URIHandler
- *
* @param application
- * Application owning the URI
+ * the Application owning the URI.
* @param request
- * HTTP request instance
+ * the HTTP request instance.
* @param response
- * HTTP response to write to.
- * @return boolean True if the request was handled and further processing
- * should be suppressed, false otherwise.
+ * the HTTP response to write to.
+ * @return boolean true
if the request was handled and further processing
+ * should be suppressed, otherwise false
.
+ * @see com.itmill.toolkit.terminal.URIHandler
*/
private DownloadStream handleURI(Application application,
HttpServletRequest request, HttpServletResponse response) {
@@ -406,21 +426,18 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
/**
- * Handle the requested URI. An application can add handlers to do special
+ * Handles the requested URI. An application can add handlers to do special
* processing, when a certain URI is requested. The handlers are invoked
* before any windows URIs are processed and if a DownloadStream is returned
* it is sent to the client.
- *
- * @see com.itmill.toolkit.terminal.URIHandler
- *
- * @param application
- * Application owning the URI
+ * @param stream the downloadable stream.
+ *
* @param request
- * HTTP request instance
+ * the HTTP request instance.
* @param response
- * HTTP response to write to.
- * @return boolean True if the request was handled and further processing
- * should be suppressed, false otherwise.
+ * the HTTP response to write to.
+ *
+ * @see com.itmill.toolkit.terminal.URIHandler
*/
private void handleDownload(DownloadStream stream,
HttpServletRequest request, HttpServletResponse response) {
@@ -429,10 +446,10 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
InputStream data = stream.getStream();
if (data != null) {
- // Set content type
+ // Sets content type
response.setContentType(stream.getContentType());
- // Set cache headers
+ // Sets cache headers
long cacheTime = stream.getCacheTime();
if (cacheTime <= 0) {
response.setHeader("Cache-Control", "no-cache");
@@ -480,7 +497,13 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
- /** End application */
+ /**
+ * Ends the Application.
+ * @param request the HTTP request instance.
+ * @param response the HTTP response to write to.
+ * @param application the Application to end.
+ * @throws IOException if the writing failed due to input/output error.
+ */
private void endApplication(HttpServletRequest request,
HttpServletResponse response, Application application)
throws IOException {
@@ -497,10 +520,11 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
out.println("");
}
- /**
- * @param window
- * @return
- */
+ /**
+ * Gets the Paintable Id.
+ * @param paintable
+ * @return the paintable Id.
+ */
public synchronized String getPaintableId(Paintable paintable) {
String id = (String) paintableIdMap.get(paintable);
@@ -511,7 +535,11 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
return id;
}
-
+
+/**
+ *
+ * @return
+ */
public synchronized Set getDirtyComponents() {
// Remove unnecessary repaints from the list
@@ -536,11 +564,18 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
return Collections.unmodifiableSet(dirtyPaintabletSet);
}
-
+
+ /**
+ * Clears the Dirty Components.
+ *
+ */
public synchronized void clearDirtyComponents() {
dirtyPaintabletSet.clear();
}
-
+
+ /**
+ * @see com.itmill.toolkit.terminal.Paintable.RepaintRequestListener#repaintRequested(com.itmill.toolkit.terminal.Paintable.RepaintRequestEvent)
+ */
public void repaintRequested(RepaintRequestEvent event) {
Paintable p = event.getPaintable();
dirtyPaintabletSet.add(p);
@@ -552,9 +587,10 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
}
- /** Recursively request repaint for all frames in frameset.
+ /**
+ * Recursively request repaint for all frames in frameset.
*
- * @param fs Framewindow.Frameset
+ * @param fs the Framewindow.Frameset.
*/
private void repaintFrameset(FrameWindow.Frameset fs) {
List frames = fs.getFrames();
@@ -570,43 +606,73 @@ public class AjaxApplicationManager implements Paintable.RepaintRequestListener,
}
}
}
-
+
+/**
+ *
+ * @param p
+ */
public void paintablePainted(Paintable p) {
dirtyPaintabletSet.remove(p);
p.requestRepaintRequests();
}
-
+
+/**
+ *
+ * @param paintable
+ * @return
+ */
public boolean isDirty(Paintable paintable) {
return (dirtyPaintabletSet.contains(paintable));
}
-
+
+ /**
+ * @see com.itmill.toolkit.Application.WindowAttachListener#windowAttached(com.itmill.toolkit.Application.WindowAttachEvent)
+ */
public void windowAttached(WindowAttachEvent event) {
event.getWindow().addListener(this);
dirtyPaintabletSet.add(event.getWindow());
}
-
+
+ /**
+ * @see com.itmill.toolkit.Application.WindowDetachListener#windowDetached(com.itmill.toolkit.Application.WindowDetachEvent)
+ */
public void windowDetached(WindowDetachEvent event) {
event.getWindow().removeListener(this);
// Notify client of the close operation
removedWindows.add(event.getWindow());
}
-
+
+/**
+ *
+ * @return
+ */
public synchronized Set getRemovedWindows() {
return Collections.unmodifiableSet(removedWindows);
}
-
+
+/**
+ *
+ * @param w
+ */
private void removedWindowNotified(Window w) {
this.removedWindows.remove(w);
}
- /** Implementation of URIHandler.ErrorEvent interface. */
+ /**
+ * Implementation of URIHandler.ErrorEvent interface.
+ */
public class URIHandlerErrorImpl implements URIHandler.ErrorEvent {
private URIHandler owner;
private Throwable throwable;
-
+
+/**
+ *
+ * @param owner
+ * @param throwable
+ */
private URIHandlerErrorImpl(URIHandler owner, Throwable throwable) {
this.owner = owner;
this.throwable = throwable;
diff --git a/src/com/itmill/toolkit/terminal/web/AjaxHttpUploadStream.java b/src/com/itmill/toolkit/terminal/web/AjaxHttpUploadStream.java
index 80529d6de8..29a9abc192 100644
--- a/src/com/itmill/toolkit/terminal/web/AjaxHttpUploadStream.java
+++ b/src/com/itmill/toolkit/terminal/web/AjaxHttpUploadStream.java
@@ -30,7 +30,8 @@ package com.itmill.toolkit.terminal.web;
import java.io.InputStream;
-/** AjaxAdapter implementation of the UploadStream interface.
+/**
+ * AjaxAdapter implementation of the UploadStream interface.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -39,22 +40,24 @@ import java.io.InputStream;
public class AjaxHttpUploadStream
implements com.itmill.toolkit.terminal.UploadStream {
- /** Holds value of property variableName. */
+ /**
+ * Holds value of property variableName.
+ */
private String streamName;
private String contentName;
private String contentType;
- /** Holds value of property variableValue. */
+ /**
+ * Holds value of property variableValue.
+ */
private InputStream stream;
- /** Creates a new instance of UploadStreamImpl
- * @param name of the stream
- * @param stream input stream
- * @param contentName name of the content
- * @param contentType type of the content
- * @param time Time of event creation
- * (for parallel events (for example in
- * same http request), times are equal)
+ /**
+ * Creates a new instance of UploadStreamImpl.
+ * @param name the name of the stream.
+ * @param stream the input stream.
+ * @param contentName the name of the content.
+ * @param contentType the type of the content.
*/
public AjaxHttpUploadStream(
String name,
@@ -67,31 +70,35 @@ public class AjaxHttpUploadStream
this.contentType = contentType;
}
- /** Get the name of the stream.
- * @return name of the stream.
+ /**
+ * Gets the name of the stream.
+ * @return the name of the stream.
*/
public String getStreamName() {
return this.streamName;
}
- /** Get input stream.
- * @return Input stream.
+ /**
+ * Gets the input stream.
+ * @return the Input stream.
*/
public InputStream getStream() {
return this.stream;
}
- /** Get input stream content type.
- * @return content type of the input stream.
+ /**
+ * Gets the input stream content type.
+ * @return the content type of the input stream.
*/
public String getContentType() {
return this.contentType;
}
- /** Get stream content name.
- * Stream content name usually differs from the actual stream name.
- * it is used toi identify the content of the stream.
- * @return Name of the stream content.
+ /**
+ * Gets the stream content name.
+ * Stream content name usually differs from the actual stream name.
+ * It is used to identify the content of the stream.
+ * @return the Name of the stream content.
*/
public String getContentName() {
return this.contentName;
diff --git a/src/com/itmill/toolkit/terminal/web/AjaxPaintTarget.java b/src/com/itmill/toolkit/terminal/web/AjaxPaintTarget.java
index fe080e2758..5db631fe2b 100644
--- a/src/com/itmill/toolkit/terminal/web/AjaxPaintTarget.java
+++ b/src/com/itmill/toolkit/terminal/web/AjaxPaintTarget.java
@@ -82,22 +82,24 @@ public class AjaxPaintTarget implements PaintTarget {
private int numberOfPaints = 0;
/**
- * Create a new XMLPrintWriter, without automatic line flushing.
+ * Creates a new XMLPrintWriter, without automatic line flushing.
*
- *
- * @param out
+ * @param variableMap
+ * @param manager
+ * @param output
* A character-output stream.
+ * @throws PaintException if the paint operation failed.
*/
public AjaxPaintTarget(AjaxVariableMap variableMap, AjaxApplicationManager manager,
OutputStream output) throws PaintException {
- // Set the cache
+ // Sets the cache
this.manager = manager;
- // Set the variable map
+ // Sets the variable map
this.variableMap = variableMap;
- // Set the target for UIDL writing
+ // Sets the target for UIDL writing
try {
this.uidlBuffer = new PrintWriter(new BufferedWriter(new OutputStreamWriter(output,"UTF-8")));
} catch (UnsupportedEncodingException e) {
@@ -108,10 +110,10 @@ public class AjaxPaintTarget implements PaintTarget {
mOpenTags = new Stack();
mTagArgumentListOpen = false;
- //Add document declaration
+ //Adds document declaration
this.print(UIDL_XML_DECL + "\n\n");
- // Add UIDL start tag and its attributes
+ // Adds UIDL start tag and its attributes
this.startTag("changes");
}
@@ -127,16 +129,16 @@ public class AjaxPaintTarget implements PaintTarget {
}
/**
- * Method append.
+ * Method append.This method is thread safe.
*
- * @param string
+ * @param string the text to insert.
*/
private void append(String string) {
uidlBuffer.print(string);
}
/**
- * Print element start tag.
+ * Prints the element start tag.
*
* * Todo: @@ -145,7 +147,8 @@ public class AjaxPaintTarget implements PaintTarget { ** * @param tagName - * The name of the start tag + * the name of the start tag. + * @throws PaintException if the paint operation failed. * */ public void startTag(String tagName) throws PaintException { @@ -153,37 +156,38 @@ public class AjaxPaintTarget implements PaintTarget { if (tagName == null) throw new NullPointerException(); - // Incerement paint tracker + // Increments paint tracker if (this.isTrackPaints()) { this.numberOfPaints++; } - //Ensure that the target is open + //Ensures that the target is open if (this.closed) throw new PaintException( "Attempted to write to a closed PaintTarget."); - // Make sure that the open start tag is closed before + // Makes sure that the open start tag is closed before // anything is written. ensureClosedTag(); - // Check tagName and attributes here + // Checks tagName and attributes here mOpenTags.push(tagName); - // Print the tag with attributes + // Prints the tag with attributes append("<" + tagName); mTagArgumentListOpen = true; } /** - * Print element end tag. + * Prints the element end tag. * * If the parent tag is closed before every child tag is closed an * PaintException is raised. * * @param tag - * The name of the end tag + * the name of the end tag. + * @throws Paintexception if the paint operation failed. */ public void endTag(String tagName) throws PaintException { // In case of null data output nothing: @@ -209,14 +213,15 @@ public class AjaxPaintTarget implements PaintTarget { mTagArgumentListOpen = false; } - //Write the end (closing) tag + //Writes the end (closing) tag append("" + lastTag + ">"); flush(); } /** - * Substitute the XML sensitive characters with predefined XML entities. - * + * Substitutes the XML sensitive characters with predefined XML entities. + * @param xml + * the String to be substituted. * @return A new string instance where all occurrences of XML sensitive * characters are substituted with entities. */ @@ -227,10 +232,10 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Substitute the XML sensitive characters with predefined XML entities. + * Substitutes the XML sensitive characters with predefined XML entities. * * @param xml - * the String to be substituted + * the String to be substituted. * @return A new StringBuffer instance where all occurrences of XML * sensitive characters are substituted with entities. * @@ -254,10 +259,10 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Substitute a XML sensitive character with predefined XML entity. + * Substitutes a XML sensitive character with predefined XML entity. * * @param c - * Character to be replaced with an entity. + * the Character to be replaced with an entity. * @return String of the entity or null if character is not to be replaced * with an entity. */ @@ -279,7 +284,7 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Print XML. + * Prints XML. * * Writes pre-formatted XML to stream. Well-formness of XML is checked. * @@ -288,6 +293,7 @@ public class AjaxPaintTarget implements PaintTarget { * TODO: XML checking should be made * * + * @param str the string to print. */ private void print(String str) { // In case of null data output nothing: @@ -303,7 +309,9 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Print XML-escaped text. + * Prints XML-escaped text. + * @param str + * @throws PaintException if the paint operation failed. * */ public void addText(String str) throws PaintException { @@ -315,9 +323,10 @@ public class AjaxPaintTarget implements PaintTarget { * content is written. * * @param name - * Attribute name + * the Attribute name. * @param value - * Attribute value + * the Attribute value. + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, boolean value) throws PaintException { addAttribute(name, String.valueOf(value)); @@ -328,9 +337,11 @@ public class AjaxPaintTarget implements PaintTarget { * any content is written. * * @param name - * Attribute name + * the Attribute name. * @param value - * Attribute value + * the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, Resource value) throws PaintException { @@ -365,10 +376,11 @@ public class AjaxPaintTarget implements PaintTarget { * content is written. * * @param name - * Attribute name + * the Attribute name. * @param value - * Attribute value - * @return this object + * the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, int value) throws PaintException { addAttribute(name, String.valueOf(value)); @@ -379,10 +391,11 @@ public class AjaxPaintTarget implements PaintTarget { * content is written. * * @param name - * Attribute name + * the Attribute name. * @param value - * Attribute value - * @return this object + * the Attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, long value) throws PaintException { addAttribute(name, String.valueOf(value)); @@ -393,10 +406,11 @@ public class AjaxPaintTarget implements PaintTarget { * content is written. * * @param name - * Boolean attribute name + * the Boolean attribute name. * @param value - * Boolean attribute value - * @return this object + * the Boolean attribute value. + * + * @throws PaintException if the paint operation failed. */ public void addAttribute(String name, String value) throws PaintException { // In case of null data output nothing: @@ -417,15 +431,16 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add a string type variable. + * Adds a string type variable. * * @param owner - * Listener for variable changes + * the Listener for variable changes. * @param name - * Variable name + * the Variable name. * @param value - * Variable initial value - * @return Reference to this. + * the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, String value) throws PaintException { @@ -439,15 +454,16 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add a int type variable. + * Adds a int type variable. * * @param owner - * Listener for variable changes + * the Listener for variable changes. * @param name - * Variable name + * the Variable name. * @param value - * Variable initial value - * @return Reference to this. + * the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, int value) throws PaintException { @@ -461,15 +477,16 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add a boolean type variable. + * Adds a boolean type variable. * * @param owner - * Listener for variable changes + * the Listener for variable changes. * @param name - * Variable name + * the Variable name. * @param value - * Variable initial value - * @return Reference to this. + * the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, boolean value) throws PaintException { @@ -483,15 +500,16 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add a string array type variable. + * Adds a string array type variable. * * @param owner - * Listener for variable changes + * the Listener for variable changes. * @param name - * Variable name + * the Variable name. * @param value - * Variable initial value - * @return Reference to this. + * the Variable initial value. + * + * @throws PaintException if the paint operation failed. */ public void addVariable(VariableOwner owner, String name, String[] value) throws PaintException { @@ -506,15 +524,14 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add a upload stream type variable. + * Adds a upload stream type variable. * * @param owner - * Listener for variable changes + * the Listener for variable changes. * @param name - * Variable name - * @param value - * Variable initial value - * @return Reference to this. + * the Variable name. + * + * @throws PaintException if the paint operation failed. */ public void addUploadStreamVariable(VariableOwner owner, String name) throws PaintException { @@ -527,10 +544,13 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Print single text section. + * Prints the single text section. * * Prints full text section. The section data is escaped from XML tags and * surrounded by XML start and end-tags. + * @param sectionTagName the name of the tag. + * @param sectionData the section data to be printed. + * @throws PaintException if the paint operation failed. */ public void addSection(String sectionTagName, String sectionData) throws PaintException { @@ -539,7 +559,11 @@ public class AjaxPaintTarget implements PaintTarget { endTag(sectionTagName); } - /** Add XML dirctly to UIDL */ + /** + * Adds XML directly to UIDL. + * @param xml the Xml to be added. + * @throws PaintException if the paint operation failed. + */ public void addUIDL(String xml) throws PaintException { //Ensure that the target is open @@ -558,7 +582,11 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Add XML section with namespace + * Adds XML section with namespace. + * @param sectionTagName the name of the tag. + * @param sectionData the section data. + * @param namespace the namespace to be added. + * @throws PaintException if the paint operation failed. * * @see com.itmill.toolkit.terminal.PaintTarget#addXMLSection(String, * String, String) @@ -583,8 +611,9 @@ public class AjaxPaintTarget implements PaintTarget { } /** - * Get the UIDL already printed to stream. Paint target must be closed - * before the getUIDL() cn be called. + * Gets the UIDL already printed to stream. Paint target must be closed + * before the
getUIDL
can be called.
+ * @return the UIDL.
*/
public String getUIDL() {
if (this.closed) {
@@ -595,10 +624,11 @@ public class AjaxPaintTarget implements PaintTarget {
}
/**
- * Close the paint target. Paint target must be closed before the getUIDL()
- * cn be called. Subsequent attempts to write to paint target. If the target
+ * Closes the paint target. Paint target must be closed before the getUIDL
+ * can be called. Subsequent attempts to write to paint target. If the target
* was already closed, call to this function is ignored. will generate an
* exception.
+ * @throws PaintException if the paint operation failed.
*/
public void close() throws PaintException {
if (!this.closed) {
@@ -631,9 +661,7 @@ public class AjaxPaintTarget implements PaintTarget {
return false;
}
- /*
- * (non-Javadoc)
- *
+ /**
* @see com.itmill.toolkit.terminal.PaintTarget#addCharacterData(java.lang.String)
*/
public void addCharacterData(String text) throws PaintException {
@@ -641,23 +669,29 @@ public class AjaxPaintTarget implements PaintTarget {
ensureClosedTag();
append(escapeXML(text));
}
-
+
+/**
+ *
+ * @return
+ */
public boolean isTrackPaints() {
return trackPaints;
}
- /** Get number of paints.
+ /**
+ * Gets the number of paints.
*
- * @return
+ * @return the number of paints.
*/
public int getNumberOfPaints() {
return numberOfPaints;
}
- /** Set tracking to true or false.
+ /**
+ * Sets the tracking to true or false.
*
* This also resets the number of paints.
- * @param trackPaints
+ * @param enabled is the tracking is enabled or not.
* @see #getNumberOfPaints()
*/
public void setTrackPaints(boolean enabled) {
diff --git a/src/com/itmill/toolkit/terminal/web/AjaxVariableMap.java b/src/com/itmill/toolkit/terminal/web/AjaxVariableMap.java
index a9f1300d1d..eb257facf1 100644
--- a/src/com/itmill/toolkit/terminal/web/AjaxVariableMap.java
+++ b/src/com/itmill/toolkit/terminal/web/AjaxVariableMap.java
@@ -50,7 +50,8 @@ import com.itmill.toolkit.terminal.Terminal;
import com.itmill.toolkit.terminal.UploadStream;
import com.itmill.toolkit.terminal.VariableOwner;
-/** Variable map for ajax applications.
+/**
+ * Variable map for ajax applications.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -66,11 +67,18 @@ public class AjaxVariableMap {
private Map idToValueMap = new HashMap();
private Map ownerToNameToIdMap = new WeakHashMap();
private Object mapLock = new Object();
-
+
// Id generator
private long lastId = 0;
- /** Convert the string to a supported class */
+ /**
+ * Converts the string to a supported class.
+ * @param type
+ * @param value
+ * @return
+ * @throws java.lang.ClassCastException if the code has
+ * attempted to cast an object to a subclass of which it is not an instance
+ */
private static Object convert(Class type, String value)
throws java.lang.ClassCastException {
try {
@@ -94,8 +102,12 @@ public class AjaxVariableMap {
}
}
- /** Register a new variable.
- *
+ /**
+ * Registers a new variable.
+ * @param name the Variable name.
+ * @param type
+ * @param value
+ * @param owner the Listener for variable changes.
* @return id to assigned for this variable.
*/
public String registerVariable(
@@ -104,7 +116,7 @@ public class AjaxVariableMap {
Object value,
VariableOwner owner) {
- // Check that the type of the class is supported
+ // Checks that the type of the class is supported
if (!(type.equals(Boolean.class)
|| type.equals(Integer.class)
|| type.equals(String.class)
@@ -115,7 +127,7 @@ public class AjaxVariableMap {
synchronized (mapLock) {
- // Check if the variable is already mapped
+ // Checks if the variable is already mapped
HashMap nameToIdMap = (HashMap) ownerToNameToIdMap.get(owner);
if (nameToIdMap == null) {
nameToIdMap = new HashMap();
@@ -124,7 +136,7 @@ public class AjaxVariableMap {
String id = (String) nameToIdMap.get(name);
if (id == null) {
- // Generate new id and register it
+ // Generates new id and register it
id = "v" + String.valueOf(++lastId);
nameToIdMap.put(name, id);
idToOwnerMap.put(id, new WeakReference(owner));
@@ -138,7 +150,11 @@ public class AjaxVariableMap {
}
}
- /** Unregisters a variable. */
+ /**
+ * Unregisters the variable.
+ * @param name the Variable name.
+ * @param owner the Listener for variable changes.
+ */
public void unregisterVariable(String name, VariableOwner owner) {
synchronized (mapLock) {
@@ -170,20 +186,31 @@ public class AjaxVariableMap {
*/
private class ParameterContainer {
- /** Construct the mapping: listener to set of listened parameter names */
+ /**
+ * Constructs the mapping: listener to set of listened parameter names.
+ */
private HashMap parameters = new HashMap();
- /** Parameter values */
+ /**
+ * Parameter values.
+ */
private HashMap values = new HashMap();
- /** Multipart parser used for parsing the request */
+ /**
+ * Multipart parser used for parsing the request.
+ */
private ServletMultipartRequest parser = null;
- /** Name - Value mapping of parameters that are not variables */
+ /**
+ * Name - Value mapping of parameters that are not variables.
+ */
private HashMap nonVariables = new HashMap();
- /** Create new parameter container and parse the parameters from the request using
+ /**
+ * Creates new parameter container and parse the parameters from the request using
* GET, POST and POST/MULTIPART parsing
+ * @param req the Http request to handle.
+ * @throws IOException if the writing failed due to input/output error.
*/
public ParameterContainer(HttpServletRequest req) throws IOException {
// Parse GET / POST parameters
@@ -235,7 +262,11 @@ public class AjaxVariableMap {
}
- /** Add parameter to container */
+ /**
+ * Adds the parameter to container.
+ * @param name the Parameter name.
+ * @param value the Parameter value.
+ */
private void addParam(String name, String[] value) {
// Support name="set:name=value" value="ignored" notation
@@ -378,13 +409,13 @@ public class AjaxVariableMap {
value = new String[0];
}
- // Get the owner
+ // Gets the owner
WeakReference ref = (WeakReference) idToOwnerMap.get(name);
VariableOwner owner = null;
if (ref != null)
owner = (VariableOwner) ref.get();
- // Add the parameter to mapping only if they have owners
+ // Adds the parameter to mapping only if they have owners
if (owner != null) {
Set p = (Set) parameters.get(owner);
if (p == null)
@@ -407,69 +438,88 @@ public class AjaxVariableMap {
idToValueMap.remove(name);
}
- // Add the parameter to set of non-variables
+ // Adds the parameter to set of non-variables
nonVariables.put(name, value);
}
}
- /** Get the set of all parameters connected to given variable owner */
+ /**
+ * Gets the set of all parameters connected to given variable owner.
+ * @param owner the Listener for variable changes.
+ * @return the set of all the parameters.
+ */
public Set getParameters(VariableOwner owner) {
if (owner == null)
return null;
return (Set) parameters.get(owner);
}
- /** Get the set of all variable owners owning parameters in this request */
+ /**
+ * Gets the set of all variable owners owning parameters in this request.
+ * @return the set of all varaible owners.
+ */
public Set getOwners() {
return parameters.keySet();
}
- /** Get the value of a parameter */
+ /**
+ * Gets the value of a parameter.
+ * @param parameterName the name of the parameter.
+ * @return the value of the parameter.
+ */
public String[] getValue(String parameterName) {
return (String[]) values.get(parameterName);
}
- /** Get the servlet multipart parser */
+ /**
+ * Gets the servlet multipart parser.
+ * @return the parser.
+ */
public ServletMultipartRequest getParser() {
return parser;
}
- /** Get the name - value[] mapping of non variable paramteres */
+ /**
+ * Gets the name - value[] mapping of non variable parameters.
+ * @return the mapping of non variable parameters.
+ */
public Map getNonVariables() {
return nonVariables;
}
}
- /** Handle all variable changes in this request.
- * @param req Http request to handle
- * @param listeners If the list is non null, only the listed listeners are
- * served. Otherwise all the listeners are served.
- * @return Name to Value[] mapping of unhandled variables
- */
+ /**
+ * Handles all variable changes in this request.
+ * @param req the Http request to handle.
+ * @param errorListener the listeners If the list is non null, only the listed listeners are
+ * served. Otherwise all the listeners are served.
+ * @return Name to Value[] mapping of unhandled variables.
+ * @throws IOException if the writing failed due to input/output error.
+ */
public Map handleVariables(
HttpServletRequest req,
Terminal.ErrorListener errorListener)
throws IOException {
- // Get the parameters
+ // Gets the parameters
ParameterContainer parcon = new ParameterContainer(req);
- // Sort listeners to dependency order
+ // Sorts listeners to dependency order
List listeners = getDependencySortedListenerList(parcon.getOwners());
- // Handle all parameters for all listeners
+ // Handles all parameters for all listeners
while (!listeners.isEmpty()) {
VariableOwner listener = (VariableOwner) listeners.remove(0);
boolean changed = false; // Has any of this owners variabes changed
- // Handle all parameters for listener
+ // Handles all parameters for listener
Set params = parcon.getParameters(listener);
if (params != null) { // Name value mapping
Map variables = new HashMap();
for (Iterator pi = params.iterator(); pi.hasNext();) {
- // Get the name of the parameter
+ // Gets the name of the parameter
String param = (String) pi.next();
- // Extract more information about the parameter
+ // Extracts more information about the parameter
String varName = (String) idToNameMap.get(param);
Class varType = (Class) idToTypeMap.get(param);
Object varOldValue = idToValueMap.get(param);
@@ -487,7 +537,7 @@ public class AjaxVariableMap {
ServletMultipartRequest parser = parcon.getParser();
- // Upload events
+ // Uploads events
if (varType.equals(UploadStream.class)) {
if (parser != null
&& parser.getFileParameter(
@@ -585,10 +635,16 @@ public class AjaxVariableMap {
return parcon.getNonVariables();
}
- /** Implementation of VariableOwner.Error interface. */
+ /**
+ * Implementation of VariableOwner.Error interface.
+ */
public class TerminalErrorImpl implements Terminal.ErrorEvent {
private Throwable throwable;
-
+
+/**
+ *
+ * @param throwable
+ */
private TerminalErrorImpl(Throwable throwable) {
this.throwable = throwable;
}
@@ -602,13 +658,19 @@ public class AjaxVariableMap {
}
- /** Implementation of VariableOwner.Error interface. */
+ /**
+ * Implementation of VariableOwner.Error interface.
+ */
public class VariableOwnerErrorImpl
extends TerminalErrorImpl
implements VariableOwner.ErrorEvent {
private VariableOwner owner;
-
+/**
+ *
+ * @param owner the Listener for variable changes.
+ * @param throwable
+ */
private VariableOwnerErrorImpl(
VariableOwner owner,
Throwable throwable) {
@@ -625,12 +687,13 @@ public class AjaxVariableMap {
}
- /** Resolve the VariableOwners needed from the request and sort
+ /**
+ * Resolves the VariableOwners needed from the request and sort
* them to assure that the dependencies are met (as well as possible).
+ *
+ * @param listeners
* @return List of variable list changers, that are needed for handling
* all the variables in the request
- * @param req request to be handled
- * @param parser multipart parser for the request
*/
private List getDependencySortedListenerList(Set listeners) {
@@ -698,12 +761,12 @@ public class AjaxVariableMap {
}
}
- // Add the listeners with dependencies in sane order to the result
+ // Adds the listeners with dependencies in sane order to the result
for (Iterator li = deepdeps.keySet().iterator(); li.hasNext();) {
VariableOwner l = (VariableOwner) li.next();
boolean immediate = l.isImmediate();
- // Add each listener after the last depended listener already in
+ // Adds each listener after the last depended listener already in
// the list
int index = -1;
for (Iterator di = ((Set) deepdeps.get(l)).iterator();
@@ -726,7 +789,7 @@ public class AjaxVariableMap {
}
}
- // Append immediate listeners to normal listeners
+ // Appends immediate listeners to normal listeners
// This way the normal handlers are always called before
// immediate ones
resultNormal.addAll(resultImmediate);
diff --git a/src/com/itmill/toolkit/terminal/web/ApplicationServlet.java b/src/com/itmill/toolkit/terminal/web/ApplicationServlet.java
index fc0c61e516..0476e60b42 100644
--- a/src/com/itmill/toolkit/terminal/web/ApplicationServlet.java
+++ b/src/com/itmill/toolkit/terminal/web/ApplicationServlet.java
@@ -103,16 +103,24 @@ public class ApplicationServlet extends HttpServlet implements
private static final long serialVersionUID = -4937882979845826574L;
- /** Version number of this release. For example "4.0.0" */
+ /**
+ * Version number of this release. For example "4.0.0".
+ */
public static final String VERSION;
- /** Major version number. For example 4 in 4.1.0. */
+ /**
+ * Major version number. For example 4 in 4.1.0.
+ */
public static final int VERSION_MAJOR;
- /** Minor version number. For example 1 in 4.1.0. */
+ /**
+ * Minor version number. For example 1 in 4.1.0.
+ */
public static final int VERSION_MINOR;
- /** Build number. For example 0-beta1 in 4.0.0-beta1. */
+ /**
+ * Builds number. For example 0-beta1 in 4.0.0-beta1.
+ */
public static final String VERSION_BUILD;
/* Initialize version numbers from string replaced by build-script. */
@@ -222,9 +230,9 @@ public class ApplicationServlet extends HttpServlet implements
* is being placed into service.
*
* @param servletConfig
- * object containing the servlet's configuration and
+ * the object containing the servlet's configuration and
* initialization parameters
- * @throws ServletException
+ * @throws javax.servlet.ServletException
* if an exception has occurred that interferes with the
* servlet's normal operation.
*/
@@ -232,14 +240,14 @@ public class ApplicationServlet extends HttpServlet implements
throws javax.servlet.ServletException {
super.init(servletConfig);
- // Get the application class name
+ // Gets the application class name
String applicationClassName = servletConfig
.getInitParameter("application");
if (applicationClassName == null) {
Log.error("Application not specified in servlet parameters");
}
- // Store the application parameters into Properties object
+ // Stores the application parameters into Properties object
this.applicationProperties = new Properties();
for (Enumeration e = servletConfig.getInitParameterNames(); e
.hasMoreElements();) {
@@ -248,7 +256,7 @@ public class ApplicationServlet extends HttpServlet implements
.getInitParameter(name));
}
- // Override with server.xml parameters
+ // Overrides with server.xml parameters
ServletContext context = servletConfig.getServletContext();
for (Enumeration e = context.getInitParameterNames(); e
.hasMoreElements();) {
@@ -257,48 +265,48 @@ public class ApplicationServlet extends HttpServlet implements
.getInitParameter(name));
}
- // Get the debug window parameter
+ // Gets the debug window parameter
String debug = getApplicationOrSystemProperty(PARAMETER_DEBUG, "")
.toLowerCase();
- // Enable application specific debug
+ // Enables application specific debug
if (!"".equals(debug) && !"true".equals(debug)
&& !"false".equals(debug))
throw new ServletException(
"If debug parameter is given for an application, it must be 'true' or 'false'");
this.debugMode = debug;
- // Get the maximum number of simultaneous transformers
+ // Gets the maximum number of simultaneous transformers
this.maxConcurrentTransformers = Integer
.parseInt(getApplicationOrSystemProperty(
PARAMETER_MAX_TRANSFORMERS, "-1"));
if (this.maxConcurrentTransformers < 1)
this.maxConcurrentTransformers = DEFAULT_MAX_TRANSFORMERS;
- // Get cache time for transformers
+ // Gets cache time for transformers
this.transformerCacheTime = Integer
.parseInt(getApplicationOrSystemProperty(
PARAMETER_TRANSFORMER_CACHETIME, "-1")) * 1000;
- // Get cache time for theme resources
+ // Gets cache time for theme resources
this.themeCacheTime = Integer.parseInt(getApplicationOrSystemProperty(
PARAMETER_THEME_CACHETIME, "-1")) * 1000;
if (this.themeCacheTime < 0) {
this.themeCacheTime = DEFAULT_THEME_CACHETIME;
}
- // Add all specified theme sources
+ // Adds all specified theme sources
this.themeSource = new CollectionThemeSource();
List directorySources = getThemeSources();
for (Iterator i = directorySources.iterator(); i.hasNext();) {
this.themeSource.add((ThemeSource) i.next());
}
- // Add the default theme source
+ // Adds the default theme source
String[] defaultThemeFiles = new String[] { getApplicationOrSystemProperty(
PARAMETER_DEFAULT_THEME_JAR, DEFAULT_THEME_JAR) };
File f = findDefaultThemeJar(defaultThemeFiles);
try {
- // Add themes.jar if exists
+ // Adds themes.jar if exists
if (f != null && f.exists())
this.themeSource.add(new JarThemeSource(f, this, ""));
else {
@@ -311,7 +319,7 @@ public class ApplicationServlet extends HttpServlet implements
+ Arrays.asList(defaultThemeFiles), e);
}
- // Check that at least one themesource was loaded
+ // Checks that at least one themesource was loaded
if (this.themeSource.getThemes().size() <= 0) {
throw new ServletException(
"No themes found in specified themesources. "
@@ -320,7 +328,7 @@ public class ApplicationServlet extends HttpServlet implements
+ "to WEB-INF/lib directory.");
}
- // Initialize the transformer factory, if not initialized
+ // Initializes the transformer factory, if not initialized
if (this.transformerFactory == null) {
this.transformerFactory = new UIDLTransformerFactory(
@@ -328,7 +336,7 @@ public class ApplicationServlet extends HttpServlet implements
this.transformerCacheTime);
}
- // Load the application class using the same class loader
+ // Loads the application class using the same class loader
// as the servlet itself
ClassLoader loader = this.getClass().getClassLoader();
try {
@@ -340,12 +348,12 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get an application or system property value.
+ * Gets an application or system property value.
*
* @param parameterName
- * Name or the parameter
+ * the Name or the parameter.
* @param defaultValue
- * Default to be used
+ * the Default to be used.
* @return String value or default if not found
*/
private String getApplicationOrSystemProperty(String parameterName,
@@ -390,13 +398,21 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get ThemeSources from given path. Construct the list of avalable themes
- * in path using the following sources: 1. content of THEME_PATH directory
- * (if available) 2. The themes listed in THEME_LIST_FILE 3. "themesource"
- * application parameter - "ThemeSource" system property
- *
- * @param THEME_DIRECTORY_PATH
- * @return List
+ * Gets ThemeSources from given path. Construct the list of avalable themes
+ * in path using the following sources:
+ *
+ * 1. Content of THEME_PATH
directory (if available).
+ *
+ * 2. The themes listed in THEME_LIST_FILE
.
+ *
+ * 3. "themesource" application parameter - "ThemeSource" system property. + *
+ * @return the List + * @throws ServletException + * if an exception has occurred that interferes with the + * servlet's normal operation. */ private List getThemeSources() throws ServletException { @@ -446,7 +462,7 @@ public class ApplicationServlet extends HttpServlet implements } } - // Add the theme sources from application properties + // Adds the theme sources from application properties String paramValue = getApplicationOrSystemProperty( PARAMETER_THEMESOURCE, null); if (paramValue != null) { @@ -456,7 +472,7 @@ public class ApplicationServlet extends HttpServlet implements } } - // Construct appropriate theme source instances for each path + // Constructs appropriate theme source instances for each path for (Iterator i = sourcePaths.iterator(); i.hasNext();) { String source = (String) i.next(); File sourceFile = new File(source); @@ -482,7 +498,7 @@ public class ApplicationServlet extends HttpServlet implements } } - // Return the constructed list of theme sources + // Returns the constructed list of theme sources return returnValue; } @@ -491,16 +507,16 @@ public class ApplicationServlet extends HttpServlet implements * dispatches them. * * @param request - * object that contains the request the client made of the - * servlet + * the object that contains the request the client made of the + * servlet. * @param response - * object that contains the response the servlet returns to the - * client + * the object that contains the response the servlet returns to the + * client. * @throws ServletException * if an input or output error occurs while the servlet is - * handling the TRACE request + * handling the TRACE request. * @throws IOException - * if the request for the TRACE cannot be handled + * if the request for the TRACE cannot be handled. */ protected void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { @@ -513,25 +529,25 @@ public class ApplicationServlet extends HttpServlet implements Application application = null; try { - // Handle resource requests + // Handles resource requests if (handleResourceRequest(request, response)) return; - // Handle server commands + // Handles server commands if (handleServerCommands(request, response)) return; - // Get the application + // Gets the application application = getApplication(request); - // Create application if it doesn't exist + // Creates application if it doesn't exist if (application == null) application = createApplication(request); - // Set the last application request date + // Sets the last application request date applicationToLastRequestDate.put(application, new Date()); - // Invoke context transaction listeners + // Invokes context transaction listeners ((WebApplicationContext) application.getContext()) .startTransaction(application, request); @@ -543,7 +559,7 @@ public class ApplicationServlet extends HttpServlet implements // made synchronized (application) { - // Handle UIDL requests? + // Handles UIDL requests? String resourceId = request.getPathInfo(); if (resourceId != null && resourceId.startsWith(AJAX_UIDL_URI)) { @@ -553,7 +569,7 @@ public class ApplicationServlet extends HttpServlet implements return; } - // Get the variable map + // Gets the variable map variableMap = getVariableMap(application, request); if (variableMap == null) return; @@ -612,7 +628,7 @@ public class ApplicationServlet extends HttpServlet implements } } - // Handle the URI if the application is still running + // Handles the URI if the application is still running if (application.isRunning()) download = handleURI(application, request, response); @@ -624,13 +640,13 @@ public class ApplicationServlet extends HttpServlet implements response.setHeader("Pragma", "no-cache"); response.setDateHeader("Expires", 0); - // Find the window within the application + // Finds the window within the application Window window = null; if (application.isRunning()) window = getApplicationWindow(request, application, unhandledParameters); - // Handle the unhandled parameters if the application is + // Handles the unhandled parameters if the application is // still running if (window != null && unhandledParameters != null && !unhandledParameters.isEmpty()) { @@ -643,13 +659,13 @@ public class ApplicationServlet extends HttpServlet implements } } - // Remove application if it has stopped + // Removes application if it has stopped if (!application.isRunning()) { endApplication(request, response, application); return; } - // Return blank page, if no window found + // Returns blank page, if no window found if (window == null) { response.setContentType("text/html"); BufferedWriter page = new BufferedWriter( @@ -673,12 +689,12 @@ public class ApplicationServlet extends HttpServlet implements return; } - // Set terminal type for the window, if not already set + // Sets terminal type for the window, if not already set if (window.getTerminal() == null) { window.setTerminal(wb); } - // Find theme + // Finds theme String themeName = window.getTheme() != null ? window .getTheme() : DEFAULT_THEME; if (unhandledParameters.get("theme") != null) { @@ -720,14 +736,14 @@ public class ApplicationServlet extends HttpServlet implements transformer = this.transformerFactory .getTransformer(transformerType); - // Set the response type + // Sets the response type response.setContentType(wb.getContentType()); - // Create UIDL writer + // Creates UIDL writer WebPaintTarget paintTarget = transformer .getPaintTarget(variableMap); - // Assure that the correspoding debug window will be + // Assures that the correspoding debug window will be // repainted property // by clearing it before the actual paint. DebugWindow debugWindow = (DebugWindow) application @@ -736,7 +752,7 @@ public class ApplicationServlet extends HttpServlet implements debugWindow.setWindowUIDL(window, "Painting..."); } - // Paint window + // Paints window window.paint(paintTarget); paintTarget.close(); @@ -760,7 +776,7 @@ public class ApplicationServlet extends HttpServlet implements .setWindowUIDL(window, paintTarget.getUIDL()); } - // Set the function library state for this thread + // Sets the function library state for this thread ThemeFunctionLibrary.setState(application, window, transformerType.getWebBrowser(), request .getSession(), this, transformerType @@ -790,7 +806,7 @@ public class ApplicationServlet extends HttpServlet implements } catch (UIDLTransformerException te) { try { - // Write the error report to client + // Writes the error report to client response.setContentType("text/html"); BufferedWriter err = new BufferedWriter(new OutputStreamWriter( out)); @@ -805,7 +821,7 @@ public class ApplicationServlet extends HttpServlet implements + ". Original exception was: ", te); } - // Add previously dirty windows to dirtyWindowList in order + // Adds previously dirty windows to dirtyWindowList in order // to make sure that eventually they are repainted Application currentApplication = getApplication(request); for (Iterator iter = currentlyDirtyWindowsForThisApplication @@ -819,21 +835,35 @@ public class ApplicationServlet extends HttpServlet implements throw new ServletException(e); } finally { - // Release transformer + // Releases transformer if (transformer != null) transformerFactory.releaseTransformer(transformer); - // Notify transaction end + // Notifies transaction end if (application != null) ((WebApplicationContext) application.getContext()) .endTransaction(application, request); - // Clean the function library state for this thread + // Cleans the function library state for this thread // for security reasons ThemeFunctionLibrary.cleanState(); } } - +/** + * + * @param request the HTTP request. + * @param response the HTTP response to write to. + * @param out + * @param unhandledParameters + * @param window + * @param terminalType + * @param theme + * @throws IOException + * if the writing failed due to input/output error. + * @throws MalformedURLException + * if the application is denied access + * the persistent data store represented by the given URL. + */ private void writeAjaxPage(HttpServletRequest request, HttpServletResponse response, OutputStream out, Map unhandledParameters, Window window, WebBrowser terminalType, @@ -931,21 +961,20 @@ public class ApplicationServlet extends HttpServlet implements } /** - * Handle the requested URI. An application can add handlers to do special + * Handles the requested URI. An application can add handlers to do special * processing, when a certain URI is requested. The handlers are invoked * before any windows URIs are processed and if a DownloadStream is returned * it is sent to the client. * - * @see com.itmill.toolkit.terminal.URIHandler - * * @param application - * Application owning the URI + * the Application owning the URI. * @param request - * HTTP request instance + * the HTTP request instance. * @param response - * HTTP response to write to. - * @return boolean True if the request was handled and further processing - * should be suppressed, false otherwise. + * the HTTP response to write to. + * @return booleantrue
if the request was handled and further processing
+ * should be suppressed, false
otherwise.
+ * @see com.itmill.toolkit.terminal.URIHandler
*/
private DownloadStream handleURI(Application application,
HttpServletRequest request, HttpServletResponse response) {
@@ -956,11 +985,11 @@ public class ApplicationServlet extends HttpServlet implements
if (uri == null || uri.length() == 0 || uri.equals("/"))
return null;
- // Remove the leading /
+ // Removes the leading /
while (uri.startsWith("/") && uri.length() > 0)
uri = uri.substring(1);
- // Handle the uri
+ // Handles the uri
DownloadStream stream = null;
try {
stream = application.handleURI(application.getURL(), uri);
@@ -972,21 +1001,19 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Handle the requested URI. An application can add handlers to do special
+ * Handles the requested URI. An application can add handlers to do special
* processing, when a certain URI is requested. The handlers are invoked
* before any windows URIs are processed and if a DownloadStream is returned
* it is sent to the client.
*
- * @see com.itmill.toolkit.terminal.URIHandler
- *
- * @param application
- * Application owning the URI
+ * @param stream the download stream.
+ *
* @param request
- * HTTP request instance
+ * the HTTP request instance.
* @param response
- * HTTP response to write to.
- * @return boolean True if the request was handled and further processing
- * should be suppressed, false otherwise.
+ * the HTTP response to write to.
+ *
+ * @see com.itmill.toolkit.terminal.URIHandler
*/
private void handleDownload(DownloadStream stream,
HttpServletRequest request, HttpServletResponse response) {
@@ -995,10 +1022,10 @@ public class ApplicationServlet extends HttpServlet implements
InputStream data = stream.getStream();
if (data != null) {
- // Set content type
+ // Sets content type
response.setContentType(stream.getContentType());
- // Set cache headers
+ // Sets cache headers
long cacheTime = stream.getCacheTime();
if (cacheTime <= 0) {
response.setHeader("Cache-Control", "no-cache");
@@ -1047,8 +1074,8 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Look for default theme JAR file.
- *
+ * Looks for default theme JAR file.
+ * @param fileList
* @return Jar file or null if not found.
*/
private File findDefaultThemeJar(String[] fileList) {
@@ -1094,13 +1121,13 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Create a temporary file for given stream.
+ * Creates a temporary file for given stream.
*
* @param stream
- * Stream to be stored into temporary file.
+ * the Stream to be stored into temporary file.
* @param extension
- * File type extension
- * @return File
+ * the File type extension.
+ * @return the temporary File.
*/
private File createTemporaryFile(InputStream stream, String extension) {
File tmpFile;
@@ -1125,15 +1152,17 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Handle theme resource file requests. Resources supplied with the themes
+ * Handles theme resource file requests. Resources supplied with the themes
* are provided by the WebAdapterServlet.
*
* @param request
- * HTTP request
+ * the HTTP request.
* @param response
- * HTTP response
- * @return boolean True if the request was handled and further processing
- * should be suppressed, false otherwise.
+ * the HTTP response.
+ * @return boolean true
if the request was handled and further processing
+ * should be suppressed, false
otherwise.
+ * @throws ServletException if an exception has occurred that interferes with the
+ * servlet's normal operation.
*/
private boolean handleResourceRequest(HttpServletRequest request,
HttpServletResponse response) throws ServletException {
@@ -1148,14 +1177,14 @@ public class ApplicationServlet extends HttpServlet implements
String resourceId = request.getPathInfo();
- // Check if this really is a resource request
+ // Checks if this really is a resource request
if (resourceId == null || !resourceId.startsWith(RESOURCE_URI))
return false;
- // Check the resource type
+ // Checks the resource type
resourceId = resourceId.substring(RESOURCE_URI.length());
InputStream data = null;
- // Get theme resources
+ // Gets theme resources
try {
data = themeSource.getResource(resourceId);
} catch (ThemeSource.ThemeException e) {
@@ -1163,7 +1192,7 @@ public class ApplicationServlet extends HttpServlet implements
data = null;
}
- // Write the response
+ // Writes the response
try {
if (data != null) {
response.setContentType(FileTypeResolver
@@ -1180,7 +1209,7 @@ public class ApplicationServlet extends HttpServlet implements
// caching in some
// Tomcats
}
- // Write the data to client
+ // Writes the data to client
byte[] buffer = new byte[DEFAULT_BUFFER_SIZE];
int bytesRead = 0;
OutputStream out = response.getOutputStream();
@@ -1201,20 +1230,26 @@ public class ApplicationServlet extends HttpServlet implements
return true;
}
- /** Get the variable map for the session */
+ /**
+ * Gets the variable map for the session.
+ * @param application
+ * @param request the HTTP request.
+ * @return the variable map.
+ *
+ */
private static synchronized HttpVariableMap getVariableMap(
Application application, HttpServletRequest request) {
HttpSession session = request.getSession();
- // Get the application to variablemap map
+ // Gets the application to variablemap map
Map varMapMap = (Map) session.getAttribute(SESSION_ATTR_VARMAP);
if (varMapMap == null) {
varMapMap = new WeakHashMap();
session.setAttribute(SESSION_ATTR_VARMAP, varMapMap);
}
- // Create a variable map, if it does not exists.
+ // Creates a variable map, if it does not exists.
HttpVariableMap variableMap = (HttpVariableMap) varMapMap
.get(application);
if (variableMap == null) {
@@ -1225,7 +1260,12 @@ public class ApplicationServlet extends HttpServlet implements
return variableMap;
}
- /** Get the current application URL from request */
+ /**
+ * Gets the current application URL from request.
+ * @param request the HTTP request.
+ * @throws MalformedURLException if the application is denied access to the
+ * persistent data store represented by the given URL.
+ */
private URL getApplicationUrl(HttpServletRequest request)
throws MalformedURLException {
@@ -1255,23 +1295,25 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get the existing application for given request. Looks for application
+ * Gets the existing application for given request. Looks for application
* instance for given request based on the requested URL.
*
* @param request
- * HTTP request
+ * the HTTP request.
* @return Application instance, or null if the URL does not map to valid
* application.
+ * @throws MalformedURLException if the application is denied access to the
+ * persistent data store represented by the given URL.
*/
private Application getApplication(HttpServletRequest request)
throws MalformedURLException {
- // Ensure that the session is still valid
+ // Ensures that the session is still valid
HttpSession session = request.getSession(false);
if (session == null)
return null;
- // Get application list for the session.
+ // Gets application list for the session.
LinkedList applications = (LinkedList) session
.getAttribute(SESSION_ATTR_APPS);
if (applications == null)
@@ -1291,7 +1333,7 @@ public class ApplicationServlet extends HttpServlet implements
application = a;
}
- // Remove stopped applications from the list
+ // Removes stopped applications from the list
if (application != null && !application.isRunning()) {
applications.remove(application);
application = null;
@@ -1301,14 +1343,27 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Create a new application.
- *
- * @return New application instance
- * @throws SAXException
- * @throws LicenseViolation
- * @throws InvalidLicenseFile
- * @throws LicenseSignatureIsInvalid
+ * Creates a new application.
+ * @param request the HTTP request.
+ * @return the New application instance.
+ * @throws MalformedURLException
+ * if the application is denied access to the persistent
+ * data store represented by the given URL.
+ * @throws InstantiationException
+ * if a new instance of the class cannot be instantiated.
+ * @throws IllegalAccessException
+ * if it does not have access to the property accessor method.
* @throws LicenseFileHasNotBeenRead
+ * if the license file has not been read.
+ * @throws LicenseSignatureIsInvalid
+ * if the license file has been changed or signature is
+ * otherwise invalid.
+ * @throws InvalidLicenseFile
+ * if the license file is not of correct XML format.
+ * @throws LicenseViolation
+ *
+ * @throws SAXException
+ * the Error parsing the license file.
*/
private Application createApplication(HttpServletRequest request)
throws MalformedURLException, InstantiationException,
@@ -1318,10 +1373,10 @@ public class ApplicationServlet extends HttpServlet implements
Application application = null;
- // Get the application url
+ // Gets the application url
URL applicationUrl = getApplicationUrl(request);
- // Get application list.
+ // Gets application list.
HttpSession session = request.getSession();
if (session == null)
return null;
@@ -1336,19 +1391,19 @@ public class ApplicationServlet extends HttpServlet implements
sessionBindingListener);
}
- // Create new application and start it
+ // Creates new application and start it
try {
application = (Application) this.applicationClass.newInstance();
applications.add(application);
- // Listen to window add/removes (for web mode)
+ // Listens to window add/removes (for web mode)
application.addListener((Application.WindowAttachListener) this);
application.addListener((Application.WindowDetachListener) this);
- // Set localte
+ // Sets localte
application.setLocale(request.getLocale());
- // Get application context for this session
+ // Gets application context for this session
WebApplicationContext context = (WebApplicationContext) session
.getAttribute(SESSION_ATTR_CONTEXT);
if (context == null) {
@@ -1356,7 +1411,7 @@ public class ApplicationServlet extends HttpServlet implements
session.setAttribute(SESSION_ATTR_CONTEXT, context);
}
- // Start application and check license
+ // Starts application and check license
initializeLicense(application);
application.start(applicationUrl, this.applicationProperties,
context);
@@ -1374,7 +1429,11 @@ public class ApplicationServlet extends HttpServlet implements
return application;
}
-
+
+/**
+ *
+ * @param application
+ */
private void initializeLicense(Application application) {
License license = (License) licenseForApplicationClass.get(application
@@ -1385,7 +1444,22 @@ public class ApplicationServlet extends HttpServlet implements
}
application.setToolkitLicense(license);
}
-
+
+/**
+ *
+ * @param application
+ * @throws LicenseFileHasNotBeenRead
+ * if the license file has not been read.
+ * @throws LicenseSignatureIsInvalid
+ * if the license file has been changed or signature is
+ * otherwise invalid.
+ * @throws InvalidLicenseFile
+ * if the license file is not of correct XML format.
+ * @throws LicenseViolation
+ *
+ * @throws SAXException
+ * the Error parsing the license file.
+ */
private void checkLicense(Application application)
throws LicenseFileHasNotBeenRead, LicenseSignatureIsInvalid,
InvalidLicenseFile, LicenseViolation, SAXException {
@@ -1422,7 +1496,7 @@ public class ApplicationServlet extends HttpServlet implements
System.out.print(license.getDescription());
}
- // Check license validity
+ // Checks license validity
try {
license.check(applicationClass, getNumberOfActiveUsers() + 1,
VERSION_MAJOR, VERSION_MINOR, "IT Mill Toolkit", null);
@@ -1442,13 +1516,13 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get the number of active application-user pairs.
+ * Gets the number of active application-user pairs.
*
* This returns total number of all applications in the server that are
* considered to be active. For an application to be active, it must have
* been accessed less than ACTIVE_USER_REQUEST_INTERVAL ms.
*
- * @return Number of active application instances in the server.
+ * @return the Number of active application instances in the server.
*/
private int getNumberOfActiveUsers() {
@@ -1464,7 +1538,13 @@ public class ApplicationServlet extends HttpServlet implements
return active;
}
- /** End application */
+ /**
+ * Ends the application.
+ * @param request the HTTP request.
+ * @param response the HTTP response to write to.
+ * @param application the application to end.
+ * @throws IOException if the writing failed due to input/output error.
+ */
private void endApplication(HttpServletRequest request,
HttpServletResponse response, Application application)
throws IOException {
@@ -1485,21 +1565,23 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get the existing application or create a new one. Get a window within an
+ * Gets the existing application or create a new one. Get a window within an
* application based on the requested URI.
*
* @param request
- * HTTP Request.
+ * the HTTP Request.
* @param application
- * Application to query for window.
+ * the Application to query for window.
* @return Window mathing the given URI or null if not found.
+ * @throws ServletException if an exception has occurred that interferes with the
+ * servlet's normal operation.
*/
private Window getApplicationWindow(HttpServletRequest request,
Application application, Map params) throws ServletException {
Window window = null;
- // Find the window where the request is handled
+ // Finds the window where the request is handled
String path = request.getPathInfo();
// Main window as the URI is empty
@@ -1539,7 +1621,7 @@ public class ApplicationServlet extends HttpServlet implements
return null;
}
}
- // Create and open new debug window for application if requested
+ // Creates and open new debug window for application if requested
Window debugWindow = application.getWindow(DebugWindow.WINDOW_NAME);
if (debugWindow == null) {
if (isDebugMode(params)
@@ -1567,12 +1649,12 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get relative location of a theme resource.
+ * Gets relative location of a theme resource.
*
* @param theme
- * Theme name
+ * the Theme name.
* @param resource
- * Theme resource
+ * the Theme resource.
* @return External URI specifying the resource
*/
public String getResourceLocation(String theme, ThemeResource resource) {
@@ -1583,10 +1665,10 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Check if web adapter is in debug mode. Extra output is generated to log
+ * Checks if web adapter is in debug mode. Extra output is generated to log
* when debug mode is enabled.
- *
- * @return Debug mode
+ * @param parameters
+ * @return true
if the web adapter is in debug mode. otherwise false
.
*/
public boolean isDebugMode(Map parameters) {
if (parameters != null) {
@@ -1606,7 +1688,12 @@ public class ApplicationServlet extends HttpServlet implements
public ThemeSource getThemeSource() {
return themeSource;
}
-
+
+/**
+ *
+ * @param application
+ * @param window
+ */
protected void addDirtyWindow(Application application, Window window) {
synchronized (applicationToDirtyWindowSetMap) {
HashSet dirtyWindows = (HashSet) applicationToDirtyWindowSetMap
@@ -1618,7 +1705,12 @@ public class ApplicationServlet extends HttpServlet implements
dirtyWindows.add(window);
}
}
-
+
+/**
+ *
+ * @param application
+ * @param window
+ */
protected void removeDirtyWindow(Application application, Window window) {
synchronized (applicationToDirtyWindowSetMap) {
HashSet dirtyWindows = (HashSet) applicationToDirtyWindowSetMap
@@ -1654,11 +1746,12 @@ public class ApplicationServlet extends HttpServlet implements
event.getWindow().removeListener(
(Paintable.RepaintRequestListener) this);
- // Add dirty window reference for closing the window
+ // Adds dirty window reference for closing the window
addDirtyWindow(event.getApplication(), event.getWindow());
}
/**
+ * Receives repaint request events.
* @see com.itmill.toolkit.terminal.Paintable.RepaintRequestListener#repaintRequested(Paintable.RepaintRequestEvent)
*/
public void repaintRequested(RepaintRequestEvent event) {
@@ -1678,7 +1771,11 @@ public class ApplicationServlet extends HttpServlet implements
}
}
- /** Get the list of dirty windows in application */
+ /**
+ * Gets the list of dirty windows in application.
+ * @param app
+ * @return
+ */
protected Set getDirtyWindows(Application app) {
HashSet dirtyWindows;
synchronized (applicationToDirtyWindowSetMap) {
@@ -1687,14 +1784,20 @@ public class ApplicationServlet extends HttpServlet implements
return dirtyWindows;
}
- /** Remove a window from the list of dirty windows */
+ /**
+ * Removes a window from the list of dirty windows.
+ * @param app
+ * @param window
+ */
private void windowPainted(Application app, Window window) {
removeDirtyWindow(app, window);
}
/**
- * Generate server commands stream. If the server commands are not
- * requested, return false
+ * Generates server commands stream. If the server commands are not
+ * requested, return false.
+ * @param request the HTTP request instance.
+ * @param response the HTTP response to write to.
*/
private boolean handleServerCommands(HttpServletRequest request,
HttpServletResponse response) {
@@ -1703,7 +1806,7 @@ public class ApplicationServlet extends HttpServlet implements
if (request.getParameter(SERVER_COMMAND_PARAM) == null)
return false;
- // Get the application
+ // Gets the application
Application application;
try {
application = getApplication(request);
@@ -1713,13 +1816,13 @@ public class ApplicationServlet extends HttpServlet implements
if (application == null)
return false;
- // Create continuous server commands stream
+ // Creates continuous server commands stream
try {
// Writer for writing the stream
PrintWriter w = new PrintWriter(response.getOutputStream());
- // Print necessary http page headers and padding
+ // Prints necessary http page headers and padding
w.println("");
for (int i = 0; i < SERVER_COMMAND_HEADER_PADDING; i++)
w.print(' ');
@@ -1782,7 +1885,7 @@ public class ApplicationServlet extends HttpServlet implements
}
}
- // Send the generated commands and newline immediately to
+ // Sends the generated commands and newline immediately to
// browser
w.println(" ");
w.flush();
@@ -1810,7 +1913,10 @@ public class ApplicationServlet extends HttpServlet implements
private class SessionBindingListener implements HttpSessionBindingListener {
private LinkedList applications;
-
+/**
+ *
+ * @param applications
+ */
protected SessionBindingListener(LinkedList applications) {
this.applications = applications;
}
@@ -1839,7 +1945,7 @@ public class ApplicationServlet extends HttpServlet implements
// Close app
((Application) apps[i]).close();
- // Stop application server commands stream
+ // Stops application server commands stream
Object lock = applicationToServerCommandStreamLock
.get(apps[i]);
if (lock != null)
@@ -1857,14 +1963,20 @@ public class ApplicationServlet extends HttpServlet implements
}
- /** Implementation of ParameterHandler.ErrorEvent interface. */
+ /**
+ * Implementation of ParameterHandler.ErrorEvent interface.
+ */
public class ParameterHandlerErrorImpl implements
ParameterHandler.ErrorEvent {
private ParameterHandler owner;
private Throwable throwable;
-
+/**
+ *
+ * @param owner
+ * @param throwable
+ */
private ParameterHandlerErrorImpl(ParameterHandler owner,
Throwable throwable) {
this.owner = owner;
@@ -1872,6 +1984,7 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
+ * Gets the contained throwable.
* @see com.itmill.toolkit.terminal.Terminal.ErrorEvent#getThrowable()
*/
public Throwable getThrowable() {
@@ -1879,6 +1992,7 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
+ * Gets the source ParameterHandler.
* @see com.itmill.toolkit.terminal.ParameterHandler.ErrorEvent#getParameterHandler()
*/
public ParameterHandler getParameterHandler() {
@@ -1887,19 +2001,26 @@ public class ApplicationServlet extends HttpServlet implements
}
- /** Implementation of URIHandler.ErrorEvent interface. */
+ /**
+ * Implementation of URIHandler.ErrorEvent interface.
+ */
public class URIHandlerErrorImpl implements URIHandler.ErrorEvent {
private URIHandler owner;
private Throwable throwable;
-
+/**
+ *
+ * @param owner
+ * @param throwable
+ */
private URIHandlerErrorImpl(URIHandler owner, Throwable throwable) {
this.owner = owner;
this.throwable = throwable;
}
/**
+ * Gets the contained throwable.
* @see com.itmill.toolkit.terminal.Terminal.ErrorEvent#getThrowable()
*/
public Throwable getThrowable() {
@@ -1907,6 +2028,7 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
+ * Gets the source URIHandler.
* @see com.itmill.toolkit.terminal.URIHandler.ErrorEvent#getURIHandler()
*/
public URIHandler getURIHandler() {
@@ -1915,7 +2037,7 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get AJAX application manager for an application.
+ * Gets AJAX application manager for an application.
*
* If this application has not been running in ajax mode before, new manager
* is created and web adapter stops listening to changes.
@@ -1930,11 +2052,11 @@ public class ApplicationServlet extends HttpServlet implements
// This application is going from Web to AJAX mode, create new manager
if (mgr == null) {
- // Create new manager
+ // Creates new manager
mgr = new AjaxApplicationManager(application);
applicationToAjaxAppMgrMap.put(application, mgr);
- // Stop sending changes to this servlet because manager will take
+ // Stops sending changes to this servlet because manager will take
// control
application.removeListener((Application.WindowAttachListener) this);
application.removeListener((Application.WindowDetachListener) this);
@@ -1952,11 +2074,12 @@ public class ApplicationServlet extends HttpServlet implements
}
/**
- * Get resource path using different implementations. Required fo supporting
+ * Gets resource path using different implementations. Required fo supporting
* different servlet container implementations (application servers).
*
- * @param path
- * @return
+ * @param servletContext
+ * @param path the resource path.
+ * @return the resource path.
*/
protected static String getResourcePath(ServletContext servletContext,
String path) {
diff --git a/src/com/itmill/toolkit/terminal/web/CollectionThemeSource.java b/src/com/itmill/toolkit/terminal/web/CollectionThemeSource.java
index 55b3bcf189..1b94e1e836 100644
--- a/src/com/itmill/toolkit/terminal/web/CollectionThemeSource.java
+++ b/src/com/itmill/toolkit/terminal/web/CollectionThemeSource.java
@@ -50,6 +50,7 @@ public class CollectionThemeSource implements ThemeSource {
private List sources = new LinkedList();
/**
+ * Gets the name of the ThemeSource.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getName()
*/
public String getName() {
@@ -57,6 +58,7 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
+ * Gets the XSL stream for the specified theme and web-browser type.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getXSLStreams(Theme,
* WebBrowser)
*/
@@ -64,10 +66,10 @@ public class CollectionThemeSource implements ThemeSource {
throws ThemeException {
Collection xslFiles = new LinkedList();
- // Add parent theme XSL
+ // Adds parent theme XSL
xslFiles.addAll(this.getParentXSLStreams(theme, type));
- // Add theme XSL, Handle subdirectories: return the first match
+ // Adds theme XSL, Handle subdirectories: return the first match
for (Iterator i = this.sources.iterator(); i.hasNext();) {
ThemeSource source = (ThemeSource) i.next();
if (source.getThemes().contains(theme))
@@ -76,7 +78,15 @@ public class CollectionThemeSource implements ThemeSource {
return xslFiles;
}
-
+
+/**
+ *
+ * @param theme
+ * @param type
+ * @return
+ * @throws ThemeException If the resource is not found or there was
+ * some problem finding the resource.
+ */
private Collection getParentXSLStreams(Theme theme, WebBrowser type)
throws ThemeException {
Collection xslFiles = new LinkedList();
@@ -94,6 +104,7 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
+ * Gets the last modification time, used to reload theme on changes.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getModificationTime()
*/
public long getModificationTime() {
@@ -107,11 +118,12 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
+ * Gets the input stream for the resource with the specified resource id.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getResource(String)
*/
public InputStream getResource(String resourceId) throws ThemeException {
- // Resolve theme name and resource name
+ // Resolves theme name and resource name
int delim = resourceId.indexOf("/");
String subResourceId = "";
String themeName = "";
@@ -120,7 +132,7 @@ public class CollectionThemeSource implements ThemeSource {
themeName = resourceId.substring(0, delim);
}
- // Get list of themes to look for the resource
+ // Gets the list of themes to look for the resource
List themes = new LinkedList();
while (themeName != null && themeName.length() > 0) {
Theme t = this.getThemeByName(themeName);
@@ -151,6 +163,7 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
+ * Gets the list of themes in the theme source.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemes()
*/
public Collection getThemes() {
@@ -163,6 +176,8 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
+ * Gets the theme instance by name.
+ * @param name the theme name.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemeByName(String)
*/
public Theme getThemeByName(String name) {
@@ -175,10 +190,10 @@ public class CollectionThemeSource implements ThemeSource {
}
/**
- * Add new theme source to this collection.
+ * Adds new theme source to this collection.
*
* @param source
- * Theme source to be added.
+ * the Theme source to be added.
*/
public void add(ThemeSource source) {
this.sources.add(source);
diff --git a/src/com/itmill/toolkit/terminal/web/DebugWindow.java b/src/com/itmill/toolkit/terminal/web/DebugWindow.java
index 7b59fd8e7f..eaafa0c219 100644
--- a/src/com/itmill/toolkit/terminal/web/DebugWindow.java
+++ b/src/com/itmill/toolkit/terminal/web/DebugWindow.java
@@ -54,7 +54,7 @@ import com.itmill.toolkit.ui.*;
* This class provides a debugging window where one may view the UIDL of
* the current window, or in a tabset the UIDL of an active frameset.
*
- * It is primarily inteded for creating and debugging themes.
+ * It is primarily intended for creating and debugging themes.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -73,10 +73,11 @@ public class DebugWindow extends Window {
private Select themeSelector;
private Label applicationInfo = new Label("", Label.CONTENT_XHTML);
- /**Create new debug window for an application.
- * @param debuggedApplication Application to be debugged.
- * @param session Session to be debugged.
- * @param servlet Servlet to be debugged.
+ /**
+ * Creates the new debug window for an application.
+ * @param debuggedApplication the Application to be debugged.
+ * @param session the Session to be debugged.
+ * @param servlet the Servlet to be debugged.
*/
protected DebugWindow(
Application debuggedApplication,
@@ -90,7 +91,7 @@ public class DebugWindow extends Window {
setBorder(Window.BORDER_NONE);
- // Create control buttons
+ // Creates control buttons
OrderedLayout controls =
new OrderedLayout(OrderedLayout.ORIENTATION_HORIZONTAL);
controls.addComponent(
@@ -103,7 +104,7 @@ public class DebugWindow extends Window {
names.add(((Theme) i.next()).getName());
}
- // Create theme selector
+ // Creates theme selector
themeSelector = new Select("Application Theme", names);
themeSelector.setWriteThrough(false);
@@ -150,11 +151,18 @@ public class DebugWindow extends Window {
termInfo.addComponent(browser);
termInfo.addComponent(setbrowser);
- // Set the debugged application
+ // Sets the debugged application
setDebuggedApplication(debuggedApplication);
}
-
+
+/**
+ *
+ * @param caption
+ * @param keys
+ * @param names
+ * @return
+ */
protected Select createSelect(
String caption,
Object[] keys,
@@ -167,7 +175,10 @@ public class DebugWindow extends Window {
s.setItemCaptionPropertyId("name");
return s;
}
-
+
+ /**
+ * Saves the UIDL.
+ */
public void saveUIDL() {
synchronized (rawUIDL) {
@@ -200,20 +211,36 @@ public class DebugWindow extends Window {
}
}
}
-
+
+ /**
+ * Commits the theme.
+ *
+ */
public void commitTheme() {
themeSelector.commit();
}
-
+
+ /**
+ * Clears the session.
+ */
public void clearSession() {
session.invalidate();
}
-
+
+ /**
+ * Restarts the Application.
+ *
+ */
public void restartApplication() {
if (debuggedApplication != null)
debuggedApplication.close();
}
-
+
+/**
+ *
+ * @param window
+ * @param uidl
+ */
protected void setWindowUIDL(Window window, String uidl) {
String caption = "UIDL:" + window.getName();
synchronized (tabs) {
@@ -236,7 +263,13 @@ public class DebugWindow extends Window {
}
}
}
-
+
+/**
+ *
+ * @param caption
+ * @param uidl
+ * @return
+ */
protected String getHTMLFormattedUIDL(String caption, String uidl) {
StringBuffer sb = new StringBuffer();
@@ -318,22 +351,21 @@ public class DebugWindow extends Window {
* with characters in the specified String
. The substring
* begins at the specified start
and extends to the character
* at index end - 1
or to the end of the
- * String
if no such character exists. First the
- * characters in the substring are removed and then the specified
+ * String
if no such character exists.
+ *
+ * First the characters in the substring are removed and then the specified
* String
is inserted at start
. (The
* StringBuffer
will be lengthened to accommodate the
* specified String if necessary.)
+ *
* NOTE: This operation is slow. *
- * - * @param start The beginning index, inclusive. - * @param end The ending index, exclusive. - * @param str String that will replace previous contents. + * @param text + * @param start the beginning index, inclusive. + * @param end the ending index, exclusive. + * @param str the String that will replace previous contents. * @return This string buffer. - * @exception StringIndexOutOfBoundsException ifstart
- * is negative, greater than length()
, or
- * greater than end
.
*/
protected static String replace(
String text,
@@ -342,7 +374,14 @@ public class DebugWindow extends Window {
String str) {
return new StringBuffer(text).replace(start, end, str).toString();
}
-
+
+/**
+ *
+ * @param text
+ * @param oldStr
+ * @param newStr
+ * @return
+ */
protected static String replaceAll(
String text,
String oldStr,
@@ -368,7 +407,7 @@ public class DebugWindow extends Window {
/**
* Sets the application.
- * @param application The application to set
+ * @param application the application to set.
*/
protected void setDebuggedApplication(Application application) {
this.debuggedApplication = application;
@@ -383,7 +422,7 @@ public class DebugWindow extends Window {
/**
* Returns the servlet.
- * @return WebAdapterServlet
+ * @return the WebAdapterServlet.
*/
protected ApplicationServlet getServlet() {
return servlet;
@@ -391,7 +430,7 @@ public class DebugWindow extends Window {
/**
* Returns the session.
- * @return HttpSession
+ * @return the HttpSession.
*/
protected HttpSession getSession() {
return session;
@@ -399,7 +438,7 @@ public class DebugWindow extends Window {
/**
* Sets the servlet.
- * @param servlet The servlet to set
+ * @param servlet the servlet to set.
*/
protected void setServlet(ApplicationServlet servlet) {
this.servlet = servlet;
@@ -407,7 +446,7 @@ public class DebugWindow extends Window {
/**
* Sets the session.
- * @param session The session to set
+ * @param session the session to set.
*/
protected void setSession(HttpSession session) {
this.session = session;
diff --git a/src/com/itmill/toolkit/terminal/web/DirectoryThemeSource.java b/src/com/itmill/toolkit/terminal/web/DirectoryThemeSource.java
index eeff3f1c86..f2df815716 100644
--- a/src/com/itmill/toolkit/terminal/web/DirectoryThemeSource.java
+++ b/src/com/itmill/toolkit/terminal/web/DirectoryThemeSource.java
@@ -49,14 +49,20 @@ public class DirectoryThemeSource implements ThemeSource {
private Theme theme;
private ApplicationServlet webAdapterServlet;
- /** Collection of subdirectory entries */
+ /**
+ * Collection of subdirectory entries.
+ */
private Collection subdirs = new LinkedList();
- /** Creates a new instance of ThemeRepository by reading the themes
+ /**
+ * Creates a new instance of ThemeRepository by reading the themes
* from a local directory.
- * @param path Path to the source directory .
- * @param url External URL of the repository
- * @throws FileNotFoundException if no theme files are found
+ * @param path the Path to the source directory .
+ * @param webAdapterServlet
+ * @throws ThemeException If the resource is not found or there was
+ * some problem finding the resource.
+ * @throws FileNotFoundException if no theme files are found.
+ * @throws IOException if the writing failed due to input/output error.
*/
public DirectoryThemeSource(File path, ApplicationServlet webAdapterServlet)
throws ThemeException, FileNotFoundException, IOException {
@@ -69,7 +75,7 @@ public class DirectoryThemeSource implements ThemeSource {
throw new java.io.FileNotFoundException(
"Theme path must be a directory ('" + this.path + "')");
- // Load description file
+ // Loads description file
File description = new File(path, Theme.DESCRIPTIONFILE);
if (description.exists()) {
try {
@@ -109,6 +115,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
/**
+ * Gets the XSL stream for the specified theme and web-browser type.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getXSLStreams(Theme, WebBrowser)
*/
public Collection getXSLStreams(Theme theme, WebBrowser type)
@@ -123,7 +130,7 @@ public class DirectoryThemeSource implements ThemeSource {
Log.info("DirectoryThemeSource: Loading XSL from: " + theme);
}
- // Reload the description file
+ // Reloads the description file
File description = new File(path, Theme.DESCRIPTIONFILE);
if (description.exists()) {
try {
@@ -136,7 +143,7 @@ public class DirectoryThemeSource implements ThemeSource {
Collection fileNames = theme.getFileNames(type, Theme.MODE_HTML);
- // Add all XSL file streams
+ // Adds all XSL file streams
for (Iterator i = fileNames.iterator(); i.hasNext();) {
File f = new File(this.path, (String) i.next());
if (f.getName().endsWith(".xsl"))
@@ -149,7 +156,7 @@ public class DirectoryThemeSource implements ThemeSource {
} else {
- // Handle subdirectories: return the first match
+ // Handles subdirectories: return the first match
for (Iterator i = this.subdirs.iterator(); i.hasNext();) {
ThemeSource source = (ThemeSource) i.next();
if (source.getThemes().contains(theme))
@@ -157,12 +164,13 @@ public class DirectoryThemeSource implements ThemeSource {
}
}
- // Return the concatenated stream
+ // Returns the concatenated stream
return xslFiles;
}
/**
+ * Gets the last modification time, used to reload theme on changes.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getModificationTime()
*/
public long getModificationTime() {
@@ -170,13 +178,13 @@ public class DirectoryThemeSource implements ThemeSource {
long modTime = 0;
// If this directory contains a theme
- // return XSL from this theme
+ // returns XSL from this theme
if (this.theme != null) {
- // Get modification time of the description file
+ // Gets modification time of the description file
modTime = new File(this.path, Theme.DESCRIPTIONFILE).lastModified();
- // Get modification time of the themes directory itself
+ // Gets modification time of the themes directory itself
if (this.path.lastModified() > modTime) {
modTime = this.path.lastModified();
}
@@ -190,7 +198,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
}
} else {
- // Handle subdirectories
+ // Handles subdirectories
for (Iterator i = this.subdirs.iterator(); i.hasNext();) {
ThemeSource source = (ThemeSource) i.next();
long t = source.getModificationTime();
@@ -204,6 +212,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
/**
+ * Gets the input stream for the resource with the specified resource id.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getResource(String)
*/
public InputStream getResource(String resourceId)
@@ -240,6 +249,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
/**
+ * Gets the list of themes in the theme source.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemes()
*/
public Collection getThemes() {
@@ -257,6 +267,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
/**
+ * Gets the name of the ThemeSource.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getName()
*/
public String getName() {
@@ -268,6 +279,7 @@ public class DirectoryThemeSource implements ThemeSource {
}
/**
+ * Gets the Theme instance by name.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemeByName(String)
*/
public Theme getThemeByName(String name) {
diff --git a/src/com/itmill/toolkit/terminal/web/HttpUploadStream.java b/src/com/itmill/toolkit/terminal/web/HttpUploadStream.java
index c3d2deb35e..0a54120ed9 100644
--- a/src/com/itmill/toolkit/terminal/web/HttpUploadStream.java
+++ b/src/com/itmill/toolkit/terminal/web/HttpUploadStream.java
@@ -30,7 +30,8 @@ package com.itmill.toolkit.terminal.web;
import java.io.InputStream;
-/** WebAdapter implementation of the UploadStream interface.
+/**
+ * WebAdapter implementation of the UploadStream interface.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -39,22 +40,24 @@ import java.io.InputStream;
public class HttpUploadStream
implements com.itmill.toolkit.terminal.UploadStream {
- /** Holds value of property variableName. */
+ /**
+ * Holds value of property variableName.
+ */
private String streamName;
private String contentName;
private String contentType;
- /** Holds value of property variableValue. */
+ /**
+ * Holds value of property variableValue.
+ */
private InputStream stream;
- /** Creates a new instance of UploadStreamImpl
- * @param name of the stream
- * @param stream input stream
- * @param contentName name of the content
- * @param contentType type of the content
- * @param time Time of event creation
- * (for parallel events (for example in
- * same http request), times are equal)
+ /**
+ * Creates a new instance of UploadStreamImpl
+ * @param name the name of the stream.
+ * @param stream the input stream.
+ * @param contentName the name of the content.
+ * @param contentType the type of the content.
*/
public HttpUploadStream(
String name,
@@ -67,31 +70,35 @@ public class HttpUploadStream
this.contentType = contentType;
}
- /** Get the name of the stream.
- * @return name of the stream.
+ /**
+ * Gets the name of the stream.
+ * @return the name of the stream.
*/
public String getStreamName() {
return this.streamName;
}
- /** Get input stream.
- * @return Input stream.
+ /**
+ * Gets the input stream.
+ * @return the Input stream.
*/
public InputStream getStream() {
return this.stream;
}
- /** Get input stream content type.
- * @return content type of the input stream.
+ /**
+ * Gets the input stream content type.
+ * @return the content type of the input stream.
*/
public String getContentType() {
return this.contentType;
}
- /** Get stream content name.
- * Stream content name usually differs from the actual stream name.
- * it is used toi identify the content of the stream.
- * @return Name of the stream content.
+ /**
+ * Gets the stream content name.
+ * Stream content name usually differs from the actual stream name.
+ * It is used to identify the content of the stream.
+ * @return the Name of the stream content.
*/
public String getContentName() {
return this.contentName;
diff --git a/src/com/itmill/toolkit/terminal/web/HttpVariableMap.java b/src/com/itmill/toolkit/terminal/web/HttpVariableMap.java
index de296b1eec..ee7033c61b 100644
--- a/src/com/itmill/toolkit/terminal/web/HttpVariableMap.java
+++ b/src/com/itmill/toolkit/terminal/web/HttpVariableMap.java
@@ -70,7 +70,12 @@ public class HttpVariableMap {
// Id generator
private long lastId = 0;
- /** Convert the string to a supported class */
+ /**
+ * Converts the string to a supported class.
+ * @param type
+ * @param value
+ * @throws java.lang.ClassCastException
+ */
private static Object convert(Class type, String value)
throws java.lang.ClassCastException {
try {
@@ -94,7 +99,12 @@ public class HttpVariableMap {
}
}
- /** Register a new variable.
+ /**
+ * Registers a new variable.
+ * @param name the name of the variable.
+ * @param type
+ * @param value
+ * @param owner the Listener for variable changes.
*
* @return id to assigned for this variable.
*/
@@ -104,7 +114,7 @@ public class HttpVariableMap {
Object value,
VariableOwner owner) {
- // Check that the type of the class is supported
+ // Checks that the type of the class is supported
if (!(type.equals(Boolean.class)
|| type.equals(Integer.class)
|| type.equals(String.class)
@@ -115,7 +125,7 @@ public class HttpVariableMap {
synchronized (mapLock) {
- // Check if the variable is already mapped
+ // Checks if the variable is already mapped
HashMap nameToIdMap = (HashMap) ownerToNameToIdMap.get(owner);
if (nameToIdMap == null) {
nameToIdMap = new HashMap();
@@ -124,7 +134,7 @@ public class HttpVariableMap {
String id = (String) nameToIdMap.get(name);
if (id == null) {
- // Generate new id and register it
+ // Generates new id and register it
id = "v" + String.valueOf(++lastId);
nameToIdMap.put(name, id);
idToOwnerMap.put(id, new WeakReference(owner));
@@ -138,12 +148,16 @@ public class HttpVariableMap {
}
}
- /** Unregisters a variable. */
+ /**
+ * Unregisters the variable.
+ * @param name the name of the variable.
+ * @param owner the Listener for variable changes.
+ */
public void unregisterVariable(String name, VariableOwner owner) {
synchronized (mapLock) {
- // Get the id
+ // Gets the id
HashMap nameToIdMap = (HashMap) ownerToNameToIdMap.get(owner);
if (nameToIdMap == null)
return;
@@ -151,7 +165,7 @@ public class HttpVariableMap {
if (id != null)
return;
- // Remove all the mappings
+ // Removes all the mappings
nameToIdMap.remove(name);
if (nameToIdMap.isEmpty())
ownerToNameToIdMap.remove(owner);
@@ -170,20 +184,31 @@ public class HttpVariableMap {
*/
private class ParameterContainer {
- /** Construct the mapping: listener to set of listened parameter names */
+ /**
+ * Constructs the mapping: listener to set of listened parameter names.
+ */
private HashMap parameters = new HashMap();
- /** Parameter values */
+ /**
+ * Parameter values.
+ */
private HashMap values = new HashMap();
- /** Multipart parser used for parsing the request */
+ /**
+ * Multipart parser used for parsing the request.
+ */
private ServletMultipartRequest parser = null;
- /** Name - Value mapping of parameters that are not variables */
+ /**
+ * Name - Value mapping of parameters that are not variables.
+ */
private HashMap nonVariables = new HashMap();
- /** Create new parameter container and parse the parameters from the request using
- * GET, POST and POST/MULTIPART parsing
+ /**
+ * Creates the new parameter container and parse the parameters from the request using
+ * GET, POST and POST/MULTIPART parsing.
+ * @param req the HTTP request.
+ * @throws IOException if the writing failed due to input/output error.
*/
public ParameterContainer(HttpServletRequest req) throws IOException {
// Parse GET / POST parameters
@@ -235,7 +260,11 @@ public class HttpVariableMap {
}
- /** Add parameter to container */
+ /**
+ * Adds the parameter to container.
+ * @param name the name of the parameter.
+ * @param value
+ */
private void addParam(String name, String[] value) {
// Support name="set:name=value" value="ignored" notation
@@ -330,7 +359,7 @@ public class HttpVariableMap {
String[] curVal = (String[]) values.get(name);
ArrayList elems = new ArrayList();
- // Add old values if present.
+ // Adds old values if present.
if (curVal != null) {
for (int i = 0; i < curVal.length; i++)
elems.add(curVal[i]);
@@ -355,7 +384,7 @@ public class HttpVariableMap {
String[] curVal = (String[]) values.get(name);
ArrayList elems = new ArrayList();
- // Add old values if present.
+ // Adds old values if present.
if (curVal != null) {
for (int i = 0; i < curVal.length; i++)
elems.add(curVal[i]);
@@ -378,13 +407,13 @@ public class HttpVariableMap {
value = new String[0];
}
- // Get the owner
+ // Gets the owner
WeakReference ref = (WeakReference) idToOwnerMap.get(name);
VariableOwner owner = null;
if (ref != null)
owner = (VariableOwner) ref.get();
- // Add the parameter to mapping only if they have owners
+ // Adds the parameter to mapping only if they have owners
if (owner != null) {
Set p = (Set) parameters.get(owner);
if (p == null)
@@ -407,58 +436,77 @@ public class HttpVariableMap {
idToValueMap.remove(name);
}
- // Add the parameter to set of non-variables
+ // Adds the parameter to set of non-variables
nonVariables.put(name, value);
}
}
- /** Get the set of all parameters connected to given variable owner */
+ /**
+ * Gets the set of all parameters connected to given variable owner.
+ * @param owner the Listener for variable changes.
+ * @return the set of all parameters connected to variable owner.
+ */
public Set getParameters(VariableOwner owner) {
if (owner == null)
return null;
return (Set) parameters.get(owner);
}
- /** Get the set of all variable owners owning parameters in this request */
+ /**
+ * Gets the set of all variable owners owning parameters in this request.
+ * @return
+ */
public Set getOwners() {
return parameters.keySet();
}
- /** Get the value of a parameter */
+ /**
+ * Gets the value of a parameter.
+ * @param parameterName the name of the parameter.
+ * @return the value of the parameter.
+ */
public String[] getValue(String parameterName) {
return (String[]) values.get(parameterName);
}
- /** Get the servlet multipart parser */
+ /**
+ * Gets the servlet multipart parser.
+ * @return the parser.
+ */
public ServletMultipartRequest getParser() {
return parser;
}
- /** Get the name - value[] mapping of non variable paramteres */
+ /**
+ * Gets the name - value[] mapping of non variable paramteres.
+ * @return
+ */
public Map getNonVariables() {
return nonVariables;
}
}
- /** Handle all variable changes in this request.
- * @param req Http request to handle
- * @param listeners If the list is non null, only the listed listeners are
- * served. Otherwise all the listeners are served.
- * @return Name to Value[] mapping of unhandled variables
- */
+ /**
+ * Handles all variable changes in this request.
+ * @param req the Http request to handle.
+ * @param errorListener If the list is non null, only the listed listeners are
+ * served. Otherwise all the listeners are served.
+ * @return Name to Value[] mapping of unhandled variables.
+ * @throws IOException if the writing failed due to input/output error.
+ */
public Map handleVariables(
HttpServletRequest req,
Terminal.ErrorListener errorListener)
throws IOException {
- // Get the parameters
+ // Gets the parameters
ParameterContainer parcon = new ParameterContainer(req);
- // Sort listeners to dependency order
+ // Sorts listeners to dependency order
List listeners = getDependencySortedListenerList(parcon.getOwners());
- // Handle all parameters for all listeners
+ // Handles all parameters for all listeners
while (!listeners.isEmpty()) {
VariableOwner listener = (VariableOwner) listeners.remove(0);
boolean changed = false; // Has any of this owners variabes changed
@@ -467,9 +515,9 @@ public class HttpVariableMap {
if (params != null) { // Name value mapping
Map variables = new HashMap();
for (Iterator pi = params.iterator(); pi.hasNext();) {
- // Get the name of the parameter
+ // Gets the name of the parameter
String param = (String) pi.next();
- // Extract more information about the parameter
+ // Extracts more information about the parameter
String varName = (String) idToNameMap.get(param);
Class varType = (Class) idToTypeMap.get(param);
Object varOldValue = idToValueMap.get(param);
@@ -582,15 +630,22 @@ public class HttpVariableMap {
return parcon.getNonVariables();
}
- /** Implementation of VariableOwner.Error interface. */
+ /**
+ * Implementation of VariableOwner.Error interface.
+ */
public class TerminalErrorImpl implements Terminal.ErrorEvent {
private Throwable throwable;
-
+
+/**
+ *
+ * @param throwable
+ */
private TerminalErrorImpl(Throwable throwable) {
this.throwable = throwable;
}
/**
+ * Gets the contained throwable.
* @see com.itmill.toolkit.terminal.Terminal.ErrorEvent#getThrowable()
*/
public Throwable getThrowable() {
@@ -599,13 +654,20 @@ public class HttpVariableMap {
}
- /** Implementation of VariableOwner.Error interface. */
+ /**
+ * Implementation of VariableOwner.Error interface.
+ */
public class VariableOwnerErrorImpl
extends TerminalErrorImpl
implements VariableOwner.ErrorEvent {
private VariableOwner owner;
-
+
+/**
+ *
+ * @param owner the Listener for variable changes.
+ * @param throwable
+ */
private VariableOwnerErrorImpl(
VariableOwner owner,
Throwable throwable) {
@@ -614,6 +676,7 @@ public class HttpVariableMap {
}
/**
+ * Gets the source VariableOwner.
* @see com.itmill.toolkit.terminal.VariableOwner.ErrorEvent#getVariableOwner()
*/
public VariableOwner getVariableOwner() {
@@ -622,12 +685,13 @@ public class HttpVariableMap {
}
- /** Resolve the VariableOwners needed from the request and sort
+ /**
+ * Resolves the VariableOwners needed from the request and sort
* them to assure that the dependencies are met (as well as possible).
+ *
+ * @param listeners
* @return List of variable list changers, that are needed for handling
* all the variables in the request
- * @param req request to be handled
- * @param parser multipart parser for the request
*/
private List getDependencySortedListenerList(Set listeners) {
@@ -695,12 +759,12 @@ public class HttpVariableMap {
}
}
- // Add the listeners with dependencies in sane order to the result
+ // Adds the listeners with dependencies in sane order to the result
for (Iterator li = deepdeps.keySet().iterator(); li.hasNext();) {
VariableOwner l = (VariableOwner) li.next();
boolean immediate = l.isImmediate();
- // Add each listener after the last depended listener already in
+ // Adds each listener after the last depended listener already in
// the list
int index = -1;
for (Iterator di = ((Set) deepdeps.get(l)).iterator();
@@ -723,7 +787,7 @@ public class HttpVariableMap {
}
}
- // Append immediate listeners to normal listeners
+ // Appends immediate listeners to normal listeners
// This way the normal handlers are always called before
// immediate ones
resultNormal.addAll(resultImmediate);
diff --git a/src/com/itmill/toolkit/terminal/web/JarThemeSource.java b/src/com/itmill/toolkit/terminal/web/JarThemeSource.java
index 0851b2a7cb..4a0707e7b0 100644
--- a/src/com/itmill/toolkit/terminal/web/JarThemeSource.java
+++ b/src/com/itmill/toolkit/terminal/web/JarThemeSource.java
@@ -69,7 +69,9 @@ public class JarThemeSource implements ThemeSource {
private Cache resourceCache = new Cache();
- /** Collection of subdirectory entries */
+ /**
+ * Collection of subdirectory entries.
+ */
private Collection subdirs = new LinkedList();
/**
@@ -77,11 +79,18 @@ public class JarThemeSource implements ThemeSource {
* local directory.
*
* @param file
- * Path to the JAR archive .
+ * the Path to the JAR archive .
+ * @param webAdapterServlet
* @param path
- * Path inside the archive to be processed.
+ * the Path inside the archive to be processed.
+ * @throws ThemeException
+ * If the resource is not found or there was
+ * some problem finding the resource.
+ *
* @throws FileNotFoundException
- * if no theme files are found
+ * if no theme files are found.
+ * @throws IOException
+ * if the writing failed due to input/output error.
*/
public JarThemeSource(File file, ApplicationServlet webAdapterServlet,
String path) throws ThemeException, FileNotFoundException,
@@ -101,7 +110,7 @@ public class JarThemeSource implements ThemeSource {
this.webAdapterServlet = webAdapterServlet;
- // Load description file
+ // Loads description file
JarEntry entry = jar.getJarEntry(this.path + Theme.DESCRIPTIONFILE);
if (entry != null) {
try {
@@ -142,6 +151,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
+ * Gets the XSL stream for the specified theme and web-browser type.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getXSLStreams(Theme,
* WebBrowser)
*/
@@ -199,7 +209,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
- * Return modication time of the jar file.
+ * Returns modication time of the jar file.
*
* @see com.itmill.toolkit.terminal.web.ThemeSource#getModificationTime()
*/
@@ -208,6 +218,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
+ * Gets the input stream for the resource with the specified resource id.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getResource(String)
*/
public InputStream getResource(String resourceId)
@@ -220,7 +231,7 @@ public class JarThemeSource implements ThemeSource {
.substring(this.theme.getName().length() + 1);
}
- // Return the resource inside the jar file
+ // Returns the resource inside the jar file
JarEntry entry = jar.getJarEntry(resourceId);
if (entry != null)
try {
@@ -230,7 +241,7 @@ public class JarThemeSource implements ThemeSource {
if (data != null)
return new ByteArrayInputStream(data);
- // Read data
+ // Reads data
int bufSize = 1024;
ByteArrayOutputStream out = new ByteArrayOutputStream(bufSize);
InputStream in = jar.getInputStream(entry);
@@ -253,6 +264,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
+ * Gets the list of themes in the theme source.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemes()
*/
public Collection getThemes() {
@@ -269,6 +281,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
+ * Gets the name of the ThemeSource.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getName()
*/
public String getName() {
@@ -280,6 +293,7 @@ public class JarThemeSource implements ThemeSource {
}
/**
+ * Gets the Theme instance by name.
* @see com.itmill.toolkit.terminal.web.ThemeSource#getThemeByName(String)
*/
public Theme getThemeByName(String name) {
@@ -301,18 +315,32 @@ public class JarThemeSource implements ThemeSource {
private class Cache {
private Map data = new HashMap();
-
+
+/**
+ *
+ * @param key
+ * @param value
+ */
public void put(Object key, Object value) {
data.put(key, new SoftReference(new CacheItem(value)));
}
-
+
+/**
+ *
+ * @param key
+ * @return
+ */
public Object get(Object key) {
SoftReference ref = (SoftReference) data.get(key);
if (ref != null)
return ((CacheItem) ref.get()).getData();
return null;
}
-
+
+ /**
+ * Clears the data.
+ *
+ */
public void clear() {
data.clear();
}
@@ -327,15 +355,26 @@ public class JarThemeSource implements ThemeSource {
private class CacheItem {
private Object data;
-
+
+/**
+ *
+ * @param data
+ */
public CacheItem(Object data) {
this.data = data;
}
-
+
+/**
+ *
+ * @return
+ */
public Object getData() {
return this.data;
};
-
+
+ /**
+ * @see java.lang.Object#finalize()
+ */
public void finalize() throws Throwable {
this.data = null;
super.finalize();
diff --git a/src/com/itmill/toolkit/terminal/web/Log.java b/src/com/itmill/toolkit/terminal/web/Log.java
index 5feec4874d..a46ba3a01b 100644
--- a/src/com/itmill/toolkit/terminal/web/Log.java
+++ b/src/com/itmill/toolkit/terminal/web/Log.java
@@ -28,24 +28,29 @@
package com.itmill.toolkit.terminal.web;
-/** Class providing centralized logging services. The logger defines +/** + *
+ * Class providing centralized logging services. The logger defines * five message types, and provides methods to create messages of those - * types. These types are:
+ * types. These types are: + * * *info
- Useful information generated during normal
- * operation of the application
+ * operation of the application.
* warning
- An error situation has occurred, but the
- * operation was able to finish succesfully
+ * operation was able to finish succesfully.
* error
- An error situation which prevented the
- * operation from finishing succesfully
+ * operation from finishing succesfully.
* debug
- Internal information from the application meant
- * for developers
+ * for developers.
* exception
- A Java exception reported using the logger.
- * Includes the exception stack trace and a possible free-form message
+ * Includes the exception stack trace and a possible free-form message.
* Currently the class offers logging only to the standard output
+ *+ * Currently the class offers logging only to the standard output. + *
* * @author IT Mill Ltd. * @version @VERSION@ @@ -61,33 +66,37 @@ public class Log { private static String LOG_MSG_DEBUG = "[DEBUG]"; private static String LOG_MSG_EXCEPT = "[EXCEPTION]"; - /** Logs awarning
message.
+ /**
+ * Logs the warning
message.
*
- * @param message Message String
to be logged.
+ * @param message the Message String to be logged.
*/
protected static synchronized void warn(java.lang.String message) {
if (Log.useStdOut) System.out.println(LOG_MSG_WARN+ " "+message);
}
- /** Logs a debug
message.
+ /**
+ * Logs the debug
message.
*
- * @param message Message String
to be logged.
+ * @param message the Message String to be logged.
*/
protected static synchronized void debug(java.lang.String message) {
if (Log.useStdOut) System.out.println(LOG_MSG_DEBUG+ " "+message);
}
- /** Logs an info
message.
+ /**
+ * Logs an info
message.
*
- * @param message Message String
to be logged.
+ * @param message the Message String to be logged.
*/
protected static synchronized void info(java.lang.String message) {
if (Log.useStdOut) System.out.println(LOG_MSG_INFO+ " "+message);
}
- /** Logs a Java exception and an accompanying error message.
+ /**
+ * Logs the Java exception and an accompanying error message.
*
- * @param message Message String
to be logged.
- * @param e Exception to be logged.
+ * @param message the Message String to be logged.
+ * @param e the Exception to be logged.
*/
protected static synchronized void except(java.lang.String message, Exception e) {
if (Log.useStdOut) {
@@ -96,9 +105,10 @@ public class Log {
}
}
- /** Logs an error
message.
+ /**
+ * Logs the error
message.
*
- * @param message Message String
to be logged.
+ * @param message the Message String to be logged.
*/
protected static synchronized void error(java.lang.String message) {
if (Log.useStdOut) System.out.println(LOG_MSG_ERROR+ " "+message);
diff --git a/src/com/itmill/toolkit/terminal/web/MultipartRequest.java b/src/com/itmill/toolkit/terminal/web/MultipartRequest.java
index 0791983b99..a6358480db 100644
--- a/src/com/itmill/toolkit/terminal/web/MultipartRequest.java
+++ b/src/com/itmill/toolkit/terminal/web/MultipartRequest.java
@@ -44,75 +44,76 @@ import java.util.Vector;
import java.io.File;
/**
- A Multipart form data parser. Parses an input stream and writes out any files found,
- making available a hashtable of other url parameters. As of version 1.17 the files can
- be saved to memory, and optionally written to a database, etc.
-
- - This library is free software; you can redistribute it and/or - modify it under the terms of the GNU Lesser General Public - License as published by the Free Software Foundation; either - version 2.1 of the License, or (at your option) any later version. -- - @author Jason Pell - - @version 1.18 Fixed some serious bugs. A new method readAndWrite(InputStream in, OutputStream out) which now does - the generic processing in common for readAndWriteFile and readFile. The differences are that now - the two extra bytes at the end of a file upload are processed once, instead of after each line. Also - if an empty file is encountered, an outputstream is opened, but then deleted if no data written to it. - The getCharArray() method has been removed. Replaced by the new String(bytes, encoding) method using - a specific encoding (Defaults to ISO-8859-1) to ensure that extended characters are supported. - All strings are processed using this encoding. The addition of static methods setEncoding(String) - and getEncoding() to allow the use of MultipartRequest with a specific encoding type. All instances - of MultipartRequest will utilise the static charEncoding variable value, that the setEncoding() method - can be used to set. Started to introduce support for multiple file uploads with the same form field - name, but not completed for v1.18. 26/06/2001 - @version 1.17 A few _very_ minor fixes. Plus a cool new feature added. The ability to save files into memory. - Thanks to Mark Latham for the idea and some of the code. 11/04/2001 - @version 1.16 Added support for multiple parameter values. Also fixed getCharArray(...) method to support - parameters with non-english ascii values (ascii above 127). Thanks to Stefan Schmidt & - Michael Elvers for this. (No fix yet for reported problems with Tomcat 3.2 or a single extra - byte appended to uploads of certain files). By 1.17 hopefully will have a resolution for the - second problem. 14/03/2001 - @version 1.15 A new parameter added, intMaxReadBytes, to allow arbitrary length files. Released under - the LGPL (Lesser General Public License). 03/02/2001 - @version 1.14 Fix for IE problem with filename being empty. This is because IE includes a default Content-Type - even when no file is uploaded. 16/02/2001 - @version 1.13 If an upload directory is not specified, then all file contents are sent into oblivion, but the - rest of the parsing works as normal. - @version 1.12 Fix, was allowing zero length files. Will not even create the output file until there is - something to write. getFile(String) now returns null, if a zero length file was specified. 06/11/2000 - @version 1.11 Fix, in case Content-type is not specified. - @version 1.1 Removed dependence on Servlets. Now passes in a generic InputStream instead. - "Borrowed" readLine from Tomcat 3.1 ServletInputStream class, - so we can remove some of the dependencies on ServletInputStream. - Fixed bug where a empty INPUT TYPE="FILE" value, would cause an exception. - @version 1.0 Initial Release. -*/ + * A Multipart form data parser. Parses an input stream and writes out any files found, + * making available a hashtable of other url parameters. As of version 1.17 the files can + * be saved to memory, and optionally written to a database, etc. + * + *
- This library is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. -
- You should have received a copy of the GNU Lesser General Public - License along with this library; if not, write to the Free Software - Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -
- Email: jasonpell@hotmail.com - Url: http://www.geocities.com/jasonpell -
+ * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + *+ * + * @author Jason Pell + * + * @version 1.18 Fixed some serious bugs. A new method readAndWrite(InputStream in, OutputStream out) which now does + * the generic processing in common for readAndWriteFile and readFile. The differences are that now + * the two extra bytes at the end of a file upload are processed once, instead of after each line. Also + * if an empty file is encountered, an outputstream is opened, but then deleted if no data written to it. + * The
+ * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + *
+ * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + *
+ * Email: jasonpell@hotmail.com + * Url: http://www.geocities.com/jasonpell + *
getCharArray
method has been removed. Replaced by the new String(bytes, encoding) method using
+ * a specific encoding (Defaults to ISO-8859-1) to ensure that extended characters are supported.
+ * All strings are processed using this encoding. The addition of static methods setEncoding(String)
+ * and getEncoding
method to allow the use of MultipartRequest
with a specific encoding type. All instances
+ * of MultipartRequest will utilise the static charEncoding variable value, that the setEncoding
method
+ * can be used to set. Started to introduce support for multiple file uploads with the same form field
+ * name, but not completed for v1.18. 26/06/2001
+ *
+ * @version 1.17 A few _very_ minor fixes. Plus a cool new feature added. The ability to save files into memory.
+ * Thanks to Mark Latham for the idea and some of the code. 11/04/2001
+ * @version 1.16 Added support for multiple parameter values. Also fixed getCharArray(...) method to support
+ * parameters with non-english ascii values (ascii above 127). Thanks to Stefan Schmidt &
+ * Michael Elvers for this. (No fix yet for reported problems with Tomcat 3.2 or a single extra
+ * byte appended to uploads of certain files). By 1.17 hopefully will have a resolution for the
+ * second problem. 14/03/2001
+ * @version 1.15 A new parameter added, intMaxReadBytes, to allow arbitrary length files. Released under
+ * the LGPL (Lesser General Public License). 03/02/2001
+ * @version 1.14 Fix for IE problem with filename being empty. This is because IE includes a default Content-Type
+ * even when no file is uploaded. 16/02/2001
+ * @version 1.13 If an upload directory is not specified, then all file contents are sent into oblivion, but the
+ * rest of the parsing works as normal.
+ * @version 1.12 Fix, was allowing zero length files. Will not even create the output file until there is
+ * something to write. getFile(String) now returns null, if a zero length file was specified. 06/11/2000
+ * @version 1.11 Fix, in case Content-type is not specified.
+ * @version 1.1 Removed dependence on Servlets. Now passes in a generic InputStream instead.
+ * "Borrowed" readLine from Tomcat 3.1 ServletInputStream class,
+ * so we can remove some of the dependencies on ServletInputStream.
+ * Fixed bug where a empty INPUT TYPE="FILE" value, would cause an exception.
+ * @version 1.0 Initial Release.
+ */
public class MultipartRequest
{
/**
- Define Character Encoding method here.
- */
+ * Defines Character Encoding method here.
+ */
private String charEncoding = "UTF-8";
// If not null, send debugging out here.
@@ -131,61 +132,61 @@ public class MultipartRequest
private long intTotalRead = -1;
/**
- Prevent a denial of service by defining this, will never read more data.
- If Content-Length is specified to be more than this, will throw an exception.
-
- This limits the maximum number of bytes to the value of an int, which is 2 Gigabytes.
- */
+ * Prevent a denial of service by defining this, will never read more data.
+ * If Content-Length is specified to be more than this, will throw an exception.
+ *
+ * This limits the maximum number of bytes to the value of an int, which is 2 Gigabytes.
+ */
public static final int MAX_READ_BYTES = Integer.MAX_VALUE;
/**
- Defines the number of bytes to read per readLine call. 128K
- */
+ * Defines the number of bytes to read per readLine call. 128K
+ */
public static final int READ_LINE_BLOCK = 1024 * 128;
/**
- Store a read from the input stream here. Global so we do not keep creating new arrays each read.
- */
+ * Store a read from the input stream here. Global so we do not keep creating new arrays each read.
+ */
private byte[] blockOfBytes = null;
/**
- Type constant for File FILENAME.
- */
+ * Type constant for File FILENAME.
+ */
public static final int FILENAME = 0;
/**
- Type constant for the File CONTENT_TYPE.
- */
+ * Type constant for the File CONTENT_TYPE.
+ */
public static final int CONTENT_TYPE = 1;
/**
- Type constant for the File SIZE.
- */
+ * Type constant for the File SIZE.
+ */
public static final int SIZE = 2;
/**
- Type constant for the File CONTENTS.
-
- Note: Only used for file upload to memory.
- */
+ * Type constant for the File CONTENTS.
+ *
+ * Note: Only used for file upload to memory.
+ */
public static final int CONTENTS = 3;
/**
- This method should be called on the MultipartRequest itself, not on any
- instances of MultipartRequest, because this sets up the encoding for all
- instances of multipartrequest. You can set the encoding to null, in which
- case the default encoding will be applied. The default encoding if this method
- is not called has been set to ISO-8859-1, which seems to offer the best hope
- of support for international characters, such as german "Umlaut" characters.
-
- Warning: In multithreaded environments it is the responsibility of the - implementer to make sure that this method is not called while another instance - is being constructed. When an instance of MultipartRequest is constructed, it parses - the input data, and uses the result of getEncoding() to convert between bytes and - strings. If setEncoding() is called by another thread, while the private parse() is - executing, the method will utilise this new encoding, which may cause serious - problems.
- */ + * This method should be called on theMultipartRequest
itself, not on any
+ * instances of MultipartRequest
, because this sets up the encoding for all
+ * instances of multipartrequest. You can set the encoding to null, in which
+ * case the default encoding will be applied. The default encoding if this method
+ * is not called has been set to ISO-8859-1, which seems to offer the best hope
+ * of support for international characters, such as german "Umlaut" characters.
+ *
+ * Warning: In multithreaded environments it is the responsibility of the
+ * implementer to make sure that this method is not called while another instance
+ * is being constructed. When an instance of MultipartRequest is constructed, it parses
+ * the input data, and uses the result of getEncoding
method to convert between bytes and
+ * strings. If setEncoding
method is called by another thread, while the private parse
method is
+ * executing, the method will utilise this new encoding, which may cause serious
+ * problems.
The getFileSystemName(String strName),getFileSize(String strName),getContentType(String strName), - getContents(String strName) methods all use this method passing in a different type argument.
- -Note: This class has been changed to provide for future functionality where you - will be able to access all files uploaded, even if they are uploaded using the same - form field name. At this point however, only the first file uploaded via a form - field name is accessible.
- - @see #getContentType(java.lang.String) - @see #getFileSize(java.lang.String) - @see #getFileContents(java.lang.String) - @see #getFileSystemName(java.lang.String) - */ + * Access an attribute of a file upload parameter record. + *The getFileSystemName(String strName),getFileSize(String strName),getContentType(String strName), + * getContents(String strName) methods all use this method passing in a different type argument.
+ * + *Note: This class has been changed to provide for future functionality where you + * will be able to access all files uploaded, even if they are uploaded using the same + * form field name. At this point however, only the first file uploaded via a form + * field name is accessible.
+ * + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * + * @param type What attribute you want from the File Parameter. + * The following types are supported: + * MultipartRequest.FILENAME, + * MultipartRequest.CONTENT_TYPE, + * MultipartRequest.SIZE, + * MultipartRequest.CONTENTS + * + * @see #getContentType(java.lang.String) + * @see #getFileSize(java.lang.String) + * @see #getFileContents(java.lang.String) + * @see #getFileSystemName(java.lang.String) + */ public Object getFileParameter(String strName, int type) { Object[] objArray = null; @@ -578,8 +591,11 @@ public class MultipartRequest } /** - This is the main parse method. - */ + * This is the main parse method. + * @param in the InputStream to read and parse. + * @throws IOException If the intContentLength is higher than MAX_READ_BYTES or + * strSaveDirectory is invalid or cannot be written to. + */ private void parse(InputStream in) throws IOException { String strContentType = null; @@ -690,9 +706,12 @@ public class MultipartRequest } /** - So we can put the logic for supporting multiple parameters with the same - form field name in the one location. - */ + * So we can put the logic for supporting multiple parameters with the same + * form field name in the one location. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @param value the form field value. + */ private void addParameter(String strName, String value) { // Fix NPE in case of null name @@ -702,7 +721,7 @@ public class MultipartRequest // Fix 1.16: for multiple parameter values. Object objParms = htParameters.get(strName); - // Add an new entry to the param vector. + // Adds an new entry to the param vector. if (objParms instanceof Vector) ((Vector)objParms).addElement(value); else if (objParms instanceof String)// There is only one entry, so we create a vector! @@ -718,11 +737,14 @@ public class MultipartRequest } /** - So we can put the logic for supporting multiple files with the same - form field name in the one location. - - Assumes that this method will never be called with a null fileObj or strFilename. - */ + * So we can put the logic for supporting multiple files with the same + * form field name in the one location. + * + * Assumes that this method will never be called with a null fileObj or strFilename. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @param fileObj + */ private void addFileParameter(String strName, Object[] fileObj) { Object objParms = htFiles.get(strName); @@ -743,10 +765,11 @@ public class MultipartRequest } /** - Read parameters, assume already passed Content-Disposition and blank line. - - @return the value read in. - */ + * Reads the parameters, assume already passed Content-Disposition and blank line. + * @param in the InputStream to read and parse. + * @return the value read in. + * @throws IOException if an error occurs writing the file. + */ private String readParameter(InputStream in) throws IOException { StringBuffer buf = new StringBuffer(); @@ -773,8 +796,11 @@ public class MultipartRequest } /** - Read from in, write to out, minus last two line ending bytes. - */ + * Read from in, write to out, minus last two line ending bytes. + * @param in the InputStream to read and parse. + * @param out the OutputStream. + * @throws IOException if an error occurs writing the file. + */ private long readAndWrite(InputStream in, OutputStream out) throws IOException { long fileSize = 0; @@ -794,7 +820,7 @@ public class MultipartRequest // Found boundary. if (readThis method does not returns -1 if it reaches the end of the input * stream before reading the maximum number of bytes, it returns -1, if no bytes read. + * @param in the InputStream to read and parse. + * @param b an array of bytes into which data is read. * - * @param b an array of bytes into which data is read - * - * @param off an integer specifying the character at which - * this method begins reading + * @param off an integer specifying the character at which + * this method begins reading. * - * @param len an integer specifying the maximum number of - * bytes to read + * @param len an integer specifying the maximum number of + * bytes to read. * - * @return an integer specifying the actual number of bytes - * read, or -1 if the end of the stream is reached + * @return an integer specifying the actual number of bytes + * read, or -1 if the end of the stream is reached. * - * @exception IOException if an input or output exception has occurred + * @throws IOException if an input or output exception has occurred * - - Note: We have a problem with Tomcat reporting an erroneous number of bytes, so we need to check this. - This is the method where we get an infinite loop, but only with binary files. + * + * Note: We have a problem with Tomcat reporting an erroneous number of bytes, so we need to check this. + * This is the method where we get an infinite loop, but only with binary files. */ private int readLine(InputStream in, byte[] b, int off, int len) throws IOException { @@ -1077,8 +1117,9 @@ public class MultipartRequest } /** - Use when debugging this object. - */ + * Prints the given debugging message. + * @param x the message to print. + */ protected void debug(String x) { if (debug!=null) @@ -1089,7 +1130,7 @@ public class MultipartRequest } /** - For debugging. + * Gets the Html Table.For debugging. */ public String getHtmlTable() { diff --git a/src/com/itmill/toolkit/terminal/web/ServletMultipartRequest.java b/src/com/itmill/toolkit/terminal/web/ServletMultipartRequest.java index 6e4e99f587..193129d95a 100644 --- a/src/com/itmill/toolkit/terminal/web/ServletMultipartRequest.java +++ b/src/com/itmill/toolkit/terminal/web/ServletMultipartRequest.java @@ -32,8 +32,9 @@ import java.io.IOException; import javax.servlet.http.HttpServletRequest; -/** This class wraps the MultipartRequest class by Jason Pell - * for the Servlet environment. +/** + * This class wraps the MultipartRequest class by Jason Pell + * for the Servlet environment. * * @author IT Mill Ltd * @version @VERSION@ @@ -43,15 +44,17 @@ public class ServletMultipartRequest extends MultipartRequest { /** * Constructor wrapper, unwraps the InputStream, - * content type and content lenght from the servlet request object. + * content type and content length from the servlet request object. * - * @param request The HttpServletRequest will be used to initialise the MultipartRequest super class. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param request the HttpServletRequest will be used to initialise the MultipartRequest super class. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. If you specify null for this parameter, then any files uploaded * will be silently ignored. * - * @exception IllegalArgumentException If the request.getContentType() does not contain a Content-Type of "multipart/form-data" or the boundary is not found. - * @exception IOException If the request.getContentLength() is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to. + * @throws IllegalArgumentException If the request.getContentType() does not contain a Content-Type + * of "multipart/form-data" or the boundary is not found. + * @throws IOException If the request.getContentLength() is higher than MAX_READ_BYTES or + * strSaveDirectory is invalid or cannot be written to. * * @see MultipartRequest#MAX_READ_BYTES */ @@ -68,16 +71,18 @@ public class ServletMultipartRequest extends MultipartRequest /** * Constructor wrapper, unwraps the InputStream, * content type and content lenght from the servlet request object. - * Also allow to explicitly set the max permissable lenght of the request. + * Also allow to explicitly set the max permissable length of the request. * - * @param request The HttpServletRequest will be used to initialise the MultipartRequest super class. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param request the HttpServletRequest will be used to initialise the MultipartRequest super class. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. If you specify null for this parameter, then any files uploaded * will be silently ignored. * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. * - * @exception IllegalArgumentException If the request.getContentType() does not contain a Content-Type of "multipart/form-data" or the boundary is not found. - * @exception IOException If the request.getContentLength() is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to. + * @throws IllegalArgumentException If the request.getContentType() does not contain a Content-Type + * of "multipart/form-data" or the boundary is not found. + * @throws IOException If the request.getContentLength() is higher than MAX_READ_BYTES + * or strSaveDirectory is invalid or cannot be written to. * * @see MultipartRequest#MAX_READ_BYTES */ @@ -94,11 +99,14 @@ public class ServletMultipartRequest extends MultipartRequest /** * Constructor wrapper for loading the request into memory rather than temp-file. * - * @param request The HttpServletRequest will be used to initialise the MultipartRequest super class. + * @param request the HttpServletRequest will be used to initialise the + * MultipartRequest super class. * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. * - * @exception IllegalArgumentException If the request.getContentType() does not contain a Content-Type of "multipart/form-data" or the boundary is not found. - * @exception IOException If the request.getContentLength() is higher than MAX_READ_BYTES or strSaveDirectory is invalid or cannot be written to. + * @throws IllegalArgumentException If the request.getContentType() does not contain a Content-Type + * of "multipart/form-data" or the boundary is not found. + * @throws IOException If the request.getContentLength() is higher than MAX_READ_BYTES + * or strSaveDirectory is invalid or cannot be written to. * * @see MultipartRequest#MAX_READ_BYTES */ diff --git a/src/com/itmill/toolkit/terminal/web/ServletThemeSource.java b/src/com/itmill/toolkit/terminal/web/ServletThemeSource.java index ed8e3b0406..231ffdc969 100644 --- a/src/com/itmill/toolkit/terminal/web/ServletThemeSource.java +++ b/src/com/itmill/toolkit/terminal/web/ServletThemeSource.java @@ -64,7 +64,9 @@ public class ServletThemeSource implements ThemeSource { private Cache resourceCache = new Cache(); - /** Collection of subdirectory entries */ + /** + * Collection of subdirectory entries. + */ private URL descFile; /** @@ -72,11 +74,13 @@ public class ServletThemeSource implements ThemeSource { * local directory. * * @param file - * Path to the JAR archive . + * the Path to the JAR archive . * @param path - * Path inside the archive to be processed. - * @throws FileNotFoundException - * if no theme files are found + * the Path inside the archive to be processed. + * @throws IOException + * if the writing failed due to input/output error. + * @throws ThemeException If the resource is not found or there was + * some problem finding the resource. */ public ServletThemeSource(ServletContext context, ApplicationServlet webAdapterServlet, String path) @@ -86,7 +90,7 @@ public class ServletThemeSource implements ThemeSource { this.webAdapterServlet = webAdapterServlet; this.context = context; - // Format path + // Formats path this.path = path; if ((this.path.length() > 0) && !this.path.endsWith("/")) { this.path = this.path + "/"; @@ -95,7 +99,7 @@ public class ServletThemeSource implements ThemeSource { this.path = "/" + this.path; } - // Load description file + // Loads description file this.descFile = context.getResource(this.path + Theme.DESCRIPTIONFILE); InputStream entry = context.getResourceAsStream(this.path + Theme.DESCRIPTIONFILE); @@ -126,6 +130,7 @@ public class ServletThemeSource implements ThemeSource { } /** + * Gets the XSL stream for the specified theme and web-browser type. * @see com.itmill.toolkit.terminal.web.ThemeSource#getXSLStreams(Theme, * WebBrowser) */ @@ -141,7 +146,7 @@ public class ServletThemeSource implements ThemeSource { Log.info("ServletThemeSource: Loading theme: " + theme); } - // Reload the description file + // Reloads the description file InputStream entry = context.getResourceAsStream(this.path + Theme.DESCRIPTIONFILE); try { @@ -160,7 +165,7 @@ public class ServletThemeSource implements ThemeSource { } Collection fileNames = theme.getFileNames(type, Theme.MODE_HTML); - // Add all XSL file streams + // Adds all XSL file streams for (Iterator i = fileNames.iterator(); i.hasNext();) { String entryName = (String) i.next(); if (entryName.endsWith(".xsl")) { @@ -176,7 +181,7 @@ public class ServletThemeSource implements ThemeSource { } /** - * Return modication time of the description file. + * Returns the modification time of the description file. * * @see com.itmill.toolkit.terminal.web.ThemeSource#getModificationTime() */ @@ -192,12 +197,13 @@ public class ServletThemeSource implements ThemeSource { } /** + * Gets the input stream for the resource with the specified resource id. * @see com.itmill.toolkit.terminal.web.ThemeSource#getResource(String) */ public InputStream getResource(String resourceId) throws ThemeSource.ThemeException { - // Check the id + // Checks the id String name = this.getName(); int namelen = name.length(); if (resourceId == null || !resourceId.startsWith(name + "/") @@ -205,7 +211,7 @@ public class ServletThemeSource implements ThemeSource { return null; } - // Find the resource + // Finds the resource String streamName = this.path + resourceId.substring(namelen + 1); InputStream stream = context.getResourceAsStream(streamName); if (stream != null) @@ -241,6 +247,7 @@ public class ServletThemeSource implements ThemeSource { } /** + * Gets the list of themes in the theme source. * @see com.itmill.toolkit.terminal.web.ThemeSource#getThemes() */ public Collection getThemes() { @@ -252,6 +259,7 @@ public class ServletThemeSource implements ThemeSource { } /** + * Gets the name of the ThemeSource. * @see com.itmill.toolkit.terminal.web.ThemeSource#getName() */ public String getName() { @@ -259,6 +267,7 @@ public class ServletThemeSource implements ThemeSource { } /** + * Gets the Theme instance by name. * @see com.itmill.toolkit.terminal.web.ThemeSource#getThemeByName(String) */ public Theme getThemeByName(String name) { @@ -280,18 +289,40 @@ public class ServletThemeSource implements ThemeSource { private class Cache { private Map data = new HashMap(); - + + /** + * Associates the specified value with the specified key in this map. + * If the map previously contained a mapping for this key, the old value + * is replaced by the specified value. + * @param key the key with which the specified value is to be associated. + * @param value the value to be associated with the specified key. + */ public void put(Object key, Object value) { data.put(key, new SoftReference(new CacheItem(value))); } - + + /** + * Returns the value to which this map maps the specified key. Returns null + * if the map contains no mapping for this key. + *
+ * A return value of null does not necessarily indicate that the map contains + * no mapping for the key; it's also possible that the map explicitly maps + * the key to null. The containsKey operation may be used to distinguish these two cases. + *
+ * @param key the key whose associated value is to be returned. + * @return the value to which this map maps the specified key, or null + * if the map contains no mapping for this key. + */ public Object get(Object key) { SoftReference ref = (SoftReference) data.get(key); if (ref != null) return ((CacheItem) ref.get()).getData(); return null; } - + + /** + * Clears the data and removes all mappings from this map . + */ public void clear() { data.clear(); } @@ -306,15 +337,35 @@ public class ServletThemeSource implements ThemeSource { private class CacheItem { private Object data; - + + /** + * + * @param data + */ public CacheItem(Object data) { this.data = data; } - + + /** + * Gets the data. + * @return the data. + */ public Object getData() { return this.data; }; - + + /** + * Called by the garbage collector on an object when garbage collection + * determines that there are no more references to the object. A subclass + * overrides the finalize method to dispose of system resources or to + * perform other cleanup. + *+ * The finalize method is never invoked more than once by a Java virtual + * machine for any given object. + *
+ * @throws Throwable the Exception raised by this method + * @see java.lang.Object#finalize() + */ public void finalize() throws Throwable { this.data = null; super.finalize(); diff --git a/src/com/itmill/toolkit/terminal/web/Theme.java b/src/com/itmill/toolkit/terminal/web/Theme.java index e7e61badbd..271add00f6 100644 --- a/src/com/itmill/toolkit/terminal/web/Theme.java +++ b/src/com/itmill/toolkit/terminal/web/Theme.java @@ -87,7 +87,9 @@ import org.xml.sax.Attributes; */ public class Theme extends DefaultHandler { - /** Default description file name. */ + /** + * Default description file name. + */ public static final String DESCRIPTIONFILE = "description.xml"; private static final String TAG_THEME = "theme"; @@ -136,40 +138,64 @@ public class Theme extends DefaultHandler { public static final String MODE_FALLBACK = MODE_HTML; - /** Name of the theme. */ + /** + * Name of the theme. + */ private String name; - /** Theme description. */ + /** + * Theme description. + */ private String description; - /** Author of the theme. */ + /** + * Author of the theme. + */ private Author author; - /** Name of the theme, which this theme extends */ + /** + * Name of the theme, which this theme extends. + */ private String parentTheme = null; - /** Fileset of included XSL files. */ + /** + * Fileset of included XSL files. + */ private Fileset files = null; - /** Stack of fileset used while parsing XML. */ + /** + * Stack of fileset used while parsing XML. + */ private Stack openFilesets = new Stack(); - /** Stack of string buffers used while parsing XML. */ + /** + * Stack of string buffers used while parsing XML. + */ private Stack openStrings = new Stack(); - /** Supported modes name-to-requirements */ + /** + * Supported modes name-to-requirements. + */ private LinkedHashMap supportedModes = new LinkedHashMap(); - /** Currently open mode */ + /** + * Currently open mode. + */ private String currentlyOpenMode = null; - /** Are we processing modes */ + /** + * Are we processing modes. + */ private boolean modesListCurrentlyOpen = false; - /** Is a NOT requirement element open. */ + /** + * Is a NOT requirement element open. + */ private boolean isNOTRequirementOpen = false; - /** Currently open requirements while parsing. */ + /** + * Currently open requirements while parsing. + */ private Stack openRequirements = new Stack(); /** @@ -177,7 +203,7 @@ public class Theme extends DefaultHandler { * by loading the description from given File. * * @param descriptionFile - * Description file + * the Description file. * @throws FileNotFoundException * Thrown if the given file is not found. */ @@ -190,7 +216,7 @@ public class Theme extends DefaultHandler { * theme, by loading the description from given InputSource. * * @param descriptionStream - * XML input to parse + * the XML input to parse */ public Theme(InputStream descriptionStream) { try { @@ -204,8 +230,10 @@ public class Theme extends DefaultHandler { } /** - * Get the preferred operating mode supported by this theme for given + * Gets the preferred operating mode supported by this theme for given * terminal. + * @param terminal the type of the web browser. + * @param themeSource */ public String getPreferredMode(WebBrowser terminal, ThemeSource themeSource) { @@ -229,7 +257,12 @@ public class Theme extends DefaultHandler { return null; } - /** Tests if this theme suppors given mode */ + /** + * Tests if this theme suppors given mode. + * @param mode + * @param terminal the type of the web browser. + * @param themeSource + */ public boolean supportsMode(String mode, WebBrowser terminal, ThemeSource themeSource) { // Theme must explicitly support the given mode @@ -252,10 +285,10 @@ public class Theme extends DefaultHandler { } /** - * Parse XML data. + * Parses the XML data. * * @param descriptionSource - * XML input source to parse + * the XML input source to parse. */ private synchronized void parse(InputSource descriptionSource) { @@ -288,7 +321,7 @@ public class Theme extends DefaultHandler { } /** - * Parse start tag in XML stream. + * Parses start tag in XML stream. * * @see org.xml.sax.ContentHandler#startElement(java.lang.String, * java.lang.String, java.lang.String, org.xml.sax.Attributes) @@ -329,12 +362,12 @@ public class Theme extends DefaultHandler { + MODE_HTML + "' and '" + MODE_AJAX + "')"); fs = new Fileset(mode); - // Use the first fileset as root fileset + // Uses the first fileset as root fileset if (this.files == null) { this.files = fs; } - // Add inner filesets to parent + // Adds inner filesets to parent if (!this.openFilesets.isEmpty()) { ((Fileset) this.openFilesets.peek()).addFile(fs); } @@ -401,7 +434,7 @@ public class Theme extends DefaultHandler { } /** - * Parse end tag in XML stream. + * Parses the end tag in XML stream. * * @see org.xml.sax.ContentHandler#endElement(String, String, String) */ @@ -430,7 +463,7 @@ public class Theme extends DefaultHandler { } /** - * Parse character data in XML stream. + * Parses the character data in XML stream. * * @see org.xml.sax.ContentHandler#characters(char[], int, int) */ @@ -446,19 +479,19 @@ public class Theme extends DefaultHandler { } /** - * Add all requirements specified in attributes to fileset. + * Adds all requirements specified in attributes to fileset. * * @param atts - * Attribute set + * the Attribute set. * @param requirements - * Collection where to add requirement rules. + * the Collection where to add requirement rules. * @param applyNot - * Should the meaning of these requirement be negated. + * the Should the meaning of these requirement be negated. */ private void addRequirements(Attributes atts, RequirementCollection requirements, boolean applyNot) { - // Create temporary collection for requirements + // Creates temporary collection for requirements Collection tmpReqs = new LinkedList(); Requirement req = null; @@ -473,12 +506,12 @@ public class Theme extends DefaultHandler { req = new MarkupLanguageRequirement(WebBrowser .parseHTMLVersion(atts.getValue(i))); } - // Add to temporary requirement collection and clear reference + // Adds to temporary requirement collection and clear reference if (req != null) tmpReqs.add(req); } - // Create implicit AND requirement if more than one + // Creates implicit AND requirement if more than one // Rrequirements were specified in attributes if (tmpReqs.size() > 1) { req = new AndRequirement(tmpReqs); @@ -489,14 +522,14 @@ public class Theme extends DefaultHandler { req = new NotRequirement(req); } - // Add to requirements + // Adds to requirements requirements.addRequirement(req); } /** - * Get list of all files in this theme. + * Gets the list of all files in this theme. * - * @return List of filenames belonging to this theme. + * @return the List of filenames belonging to this theme. */ public List getFileNames() { if (files == null) @@ -505,9 +538,10 @@ public class Theme extends DefaultHandler { } /** - * Get list of file names matching WebBrowserType. - * - * @return list of filenames in this theme supporting the given terminal. + * Gets the list of file names matching WebBrowserType. + * @param terminal the type of the web browser. + * @param mode + * @return the list of filenames in this theme supporting the given terminal. */ public List getFileNames(WebBrowser terminal, String mode) { if (files == null) @@ -536,29 +570,34 @@ public class Theme extends DefaultHandler { * @since 3.0 */ public class Author { - + //name of the author. private String name; - + //email address of the author. private String email; - + + /** + * Constructor for Author Information Class. + * @param name the name of the author. + * @param email the email address of the author. + */ public Author(String name, String email) { this.name = name; this.email = email; } /** - * Get the name of the author. + * Gets the name of the author. * - * @return Name of the author. + * @return the Name of the author. */ public String getName() { return this.name; } /** - * Get the email address of the author. + * Gets the email address of the author. * - * @return Email address of the author. + * @return the Email address of the author. */ public String getEmail() { return this.email; @@ -573,7 +612,7 @@ public class Theme extends DefaultHandler { } /** - * Generic requirement. Interface implemented by reuirements introducing + * Generic requirement. Interface implemented by requirements introducing * method for checking compability with given terminal. * * @author IT Mill Ltd. @@ -584,12 +623,12 @@ public class Theme extends DefaultHandler { public interface Requirement { /** - * Check that this requirement is met by given type of browser. + * Checks that this requirement is met by given type of browser. * * @param terminal - * type of the web browser. - * @return True if terminal is compatible with this rule. False - * otherwise. + * the type of the web browser. + * @returntrue
if terminal is compatible with this rule,otherwise false
.
+ *
*/
public boolean isMet(WebBrowser terminal);
@@ -607,18 +646,18 @@ public class Theme extends DefaultHandler {
public interface RequirementCollection extends Requirement {
/**
- * Add new requirement to this collection.
+ * Adds the new requirement to this collection.
*
* @param requirement
- * Requirement to be added.
+ * the Requirement to be added.
*/
public void addRequirement(Requirement requirement);
/**
- * Remove a requirement from this collection.
+ * Removes the requirement from this collection.
*
* @param requirement
- * Requirement to be removed.
+ * the Requirement to be removed.
*/
public void removeRequirement(Requirement requirement);
}
@@ -639,7 +678,7 @@ public class Theme extends DefaultHandler {
* Create new NOT requirement based on another requirement.
*
* @param requirement
- * The requirement to ne negated.
+ * the requirement to be negated.
*/
public NotRequirement(Requirement requirement) {
this.requirement = requirement;
@@ -649,9 +688,9 @@ public class Theme extends DefaultHandler {
* Check that this requirement is met by given type of browser.
*
* @param terminal
- * type of the web browser.
- * @return True if terminal is compatible with this rule. False
- * otherwise.
+ * the type of the web browser.
+ * @return true
if terminal is compatible with this rule,otherwise false
.
+ *
*/
public boolean isMet(WebBrowser terminal) {
return !this.requirement.isMet(terminal);
@@ -681,27 +720,44 @@ public class Theme extends DefaultHandler {
public AndRequirement() {
}
-
+
+ /**
+ *
+ * @param requirements
+ */
public AndRequirement(Collection requirements) {
this.requirements.addAll(requirements);
}
-
+
+ /**
+ *
+ * @param req1
+ * @param req2
+ */
public AndRequirement(Requirement req1, Requirement req2) {
this.addRequirement(req1);
this.addRequirement(req2);
}
-
+
+ /**
+ * Adds the new requirement to this collection.
+ * @see com.itmill.toolkit.terminal.web.Theme.RequirementCollection#addRequirement(com.itmill.toolkit.terminal.web.Theme.Requirement)
+ */
public void addRequirement(Requirement requirement) {
this.requirements.add(requirement);
}
-
+
+ /**
+ * Removes the requirement from this collection.
+ * @see com.itmill.toolkit.terminal.web.Theme.RequirementCollection#removeRequirement(com.itmill.toolkit.terminal.web.Theme.Requirement)
+ */
public void removeRequirement(Requirement requirement) {
this.requirements.remove(requirement);
}
/**
* Checks that all os the requirements in this collection are met.
- *
+ * @param terminal the type of the web browser.
* @see Theme.Requirement#isMet(WebBrowser)
*/
public boolean isMet(WebBrowser terminal) {
@@ -712,7 +768,10 @@ public class Theme extends DefaultHandler {
}
return true;
}
-
+
+ /**
+ * @see java.lang.Object#toString()
+ */
public String toString() {
String str = "";
for (Iterator i = this.requirements.iterator(); i.hasNext();) {
@@ -740,27 +799,44 @@ public class Theme extends DefaultHandler {
public OrRequirement() {
}
-
+
+ /**
+ *
+ * @param requirements
+ */
public OrRequirement(Collection requirements) {
this.requirements.addAll(requirements);
}
-
+
+ /**
+ *
+ * @param req1
+ * @param req2
+ */
public OrRequirement(Requirement req1, Requirement req2) {
this.addRequirement(req1);
this.addRequirement(req2);
}
-
+
+ /**
+ * Adds the new requirement to this collection.
+ * @see com.itmill.toolkit.terminal.web.Theme.RequirementCollection#addRequirement(com.itmill.toolkit.terminal.web.Theme.Requirement)
+ */
public void addRequirement(Requirement requirement) {
this.requirements.add(requirement);
}
-
+
+ /**
+ * Removes the requirement from this collection.
+ * @see com.itmill.toolkit.terminal.web.Theme.RequirementCollection#removeRequirement(com.itmill.toolkit.terminal.web.Theme.Requirement)
+ */
public void removeRequirement(Requirement requirement) {
this.requirements.remove(requirement);
}
/**
* Checks that some of the requirements in this collection is met.
- *
+ * @param terminal the type of the web browser.
* @see Theme.Requirement#isMet(WebBrowser)
*/
public boolean isMet(WebBrowser terminal) {
@@ -771,7 +847,10 @@ public class Theme extends DefaultHandler {
}
return false;
}
-
+
+ /**
+ * @see java.lang.Object#toString()
+ */
public String toString() {
String str = "";
for (Iterator i = this.requirements.iterator(); i.hasNext();) {
@@ -796,11 +875,19 @@ public class Theme extends DefaultHandler {
public class AgentRequirement implements Requirement {
private String agentSubstring;
-
+
+ /**
+ *
+ * @param agentSubString
+ */
public AgentRequirement(String agentSubString) {
this.agentSubstring = agentSubString;
}
-
+
+ /**
+ * Checks that this requirement is met by given type of browser.
+ * @see com.itmill.toolkit.terminal.web.Theme.Requirement#isMet(com.itmill.toolkit.terminal.web.WebBrowser)
+ */
public boolean isMet(WebBrowser terminal) {
return terminal.getBrowserApplication().indexOf(this.agentSubstring) >= 0;
}
@@ -825,12 +912,20 @@ public class Theme extends DefaultHandler {
public class JavaScriptRequirement implements Requirement {
private WebBrowser.JavaScriptVersion requiredVersion;
-
+
+ /**
+ *
+ * @param requiredVersion
+ */
public JavaScriptRequirement(
WebBrowser.JavaScriptVersion requiredVersion) {
this.requiredVersion = requiredVersion;
}
-
+
+ /**
+ * Checks that this requirement is met by given type of browser.
+ * @see com.itmill.toolkit.terminal.web.Theme.Requirement#isMet(com.itmill.toolkit.terminal.web.WebBrowser)
+ */
public boolean isMet(WebBrowser terminal) {
if (terminal.getJavaScriptVersion().supports(this.requiredVersion))
return true;
@@ -846,7 +941,7 @@ public class Theme extends DefaultHandler {
}
/**
- * Markup language version requirement This requirement is used to ensure a
+ * Markup language version requirement. This requirement is used to ensure a
* certain level of Markup language version support.
*
* @author IT Mill Ltd.
@@ -857,12 +952,20 @@ public class Theme extends DefaultHandler {
public class MarkupLanguageRequirement implements Requirement {
private WebBrowser.MarkupVersion requiredVersion;
-
+
+ /**
+ *
+ * @param requiredVersion
+ */
public MarkupLanguageRequirement(
WebBrowser.MarkupVersion requiredVersion) {
this.requiredVersion = requiredVersion;
}
-
+
+ /**
+ * Checks that this requirement is met by given type of browser.
+ * @see com.itmill.toolkit.terminal.web.Theme.Requirement#isMet(com.itmill.toolkit.terminal.web.WebBrowser)
+ */
public boolean isMet(WebBrowser terminal) {
if (terminal.getMarkupVersion().supports(this.requiredVersion))
return true;
@@ -893,20 +996,20 @@ public class Theme extends DefaultHandler {
private String name;
/**
- * Create new file.
+ * Creates the new file.
*
* @param name
- * Name of the file.
+ * the Name of the file.
*/
public File(String name) {
this.name = name;
}
/**
- * Get name of the file. The file name is relative and unique within a
+ * Gets the name of the file. The file name is relative and unique within a
* theme.
*
- * @return Name of the file.
+ * @return the Name of the file.
*/
public String getName() {
return this.name;
@@ -915,9 +1018,9 @@ public class Theme extends DefaultHandler {
/**
* Does this file support the given terminal. Single file requirements
* are not supported and therefore this always returns true.
- *
- * @see Theme.Fileset
+ * @param terminal the type of the web browser.
* @return Always returns true.
+ * @see Theme.Fileset
*/
public boolean supports(WebBrowser terminal) {
return true;
@@ -949,30 +1052,36 @@ public class Theme extends DefaultHandler {
private String mode;
/**
- * Create new empty fileset.
+ * Creates the new empty fileset.
*
- * @param name
- * Name of the fileset.
+ * @param mode
+ *
*/
public Fileset(String mode) {
super(null);
this.mode = mode;
}
- /** Add a file into fileset. */
+ /**
+ * Adds a file into fileset.
+ * @param file the file to add.
+ */
private void addFile(File file) {
this.files.add(file);
}
- /** Get requirements in this fileset. */
+ /**
+ * Gets the requirements in this fileset.
+ * @return the requirements.
+ */
private RequirementCollection getRequirements() {
return this.requirements;
}
/**
- * Get list of all files in this theme.
+ * Gets the list of all files in this theme.
*
- * @return list of filenames.
+ * @return the list of filenames.
*/
public List getFileNames() {
@@ -993,9 +1102,10 @@ public class Theme extends DefaultHandler {
}
/**
- * Get list of file names matching WebBrowserType.
- *
- * @return list of filenames supporting the given terminal.
+ * Gets the list of file names matching WebBrowserType.
+ * @param terminal the type of the web browser.
+ * @param mode
+ * @return the list of filenames supporting the given terminal.
*/
public List getFileNames(WebBrowser terminal, String mode) {
@@ -1025,7 +1135,7 @@ public class Theme extends DefaultHandler {
/**
* Does this file support the given terminal.
- *
+ * @terminal the type of the web browser.
* @return True if fileset supports the given browser. False otherwise.
*/
public boolean supports(WebBrowser terminal) {
@@ -1044,32 +1154,35 @@ public class Theme extends DefaultHandler {
}
/**
- * Returns the author of this theme.
+ * Gets the author of this theme.
*
- * @return Author of the theme.
+ * @return the Author of the theme.
*/
public Author getAuthor() {
return author;
}
/**
- * Returns the name of this theme.
+ * Gets the name of this theme.
*
- * @return Name of the theme.
+ * @return the Name of the theme.
*/
public String getName() {
return name;
}
/**
- * Returns the name of the parent theme.
- *
+ * Gets the name of the parent theme.
+ * @return the name of the parent theme.
*/
public String getParent() {
return parentTheme;
}
- /** Get theme description */
+ /**
+ * Gets the theme description.
+ * @return the theme description.
+ */
public String getDescription() {
return description;
}
diff --git a/src/com/itmill/toolkit/terminal/web/ThemeFunctionLibrary.java b/src/com/itmill/toolkit/terminal/web/ThemeFunctionLibrary.java
index 41b6e63d38..79417700b6 100644
--- a/src/com/itmill/toolkit/terminal/web/ThemeFunctionLibrary.java
+++ b/src/com/itmill/toolkit/terminal/web/ThemeFunctionLibrary.java
@@ -48,7 +48,7 @@ import javax.servlet.http.HttpSession;
* This a function library that can be used from the theme XSL-files. It
* provides easy access to current application, window, theme, webbrowser and
* session. The internal threadlocal state must be maintained by the webadapter
- * in order go guarantee that it works.
+ * in order to guarantee that it works.
*
* @author IT Mill Ltd.
* @version
@@ -71,7 +71,16 @@ public class ThemeFunctionLibrary {
static private final int THEME = 5;
static private ThreadLocal state = new ThreadLocal();
-
+
+/**
+ *
+ * @param application
+ * @param window
+ * @param webBrowser
+ * @param session
+ * @param webAdapterServlet
+ * @param theme
+ */
static protected void setState(Application application, Window window,
WebBrowser webBrowser, HttpSession session,
ApplicationServlet webAdapterServlet, String theme) {
@@ -132,7 +141,7 @@ public class ThemeFunctionLibrary {
}
/**
- * Return a reference to the current theme name that is associated with the
+ * Returns a reference to the current theme name that is associated with the
* session that the call came from.
*/
static public String theme() {
@@ -144,7 +153,9 @@ public class ThemeFunctionLibrary {
}
/**
- * Return an URI to the named resource from the named theme.
+ * Returns an URI to the named resource from the named theme.
+ * @param resource
+ * @param theme
*/
static public String resource(String resource, String theme) {
try {
@@ -156,7 +167,8 @@ public class ThemeFunctionLibrary {
}
/**
- * Return an URI to the named resource.
+ * Returns an URI to the named resource.
+ * @param resource
*/
static public String resource(String resource) {
try {
@@ -168,7 +180,7 @@ public class ThemeFunctionLibrary {
}
/**
- * Generate JavaScript for page that performs client-side combility checks.
+ * Generates the JavaScript for page that performs client-side combility checks.
*/
static public boolean probeClient() {
return (browser().performClientCheck() && !browser()
@@ -176,7 +188,7 @@ public class ThemeFunctionLibrary {
}
/**
- * Generate JavaScript for page header that handles window refreshing,
+ * Generates the JavaScript for page header that handles window refreshing,
* opening and closing.
*
* Generates script that:
@@ -185,7 +197,7 @@ public class ThemeFunctionLibrary {
* * This returns the action for the window main form. This action can be set * through WebApplicationContect setWindowFormAction method.. *
* - * @return Form action for the current window. + * @return the Form action for the current window. */ static public String getFormAction() { @@ -437,7 +450,10 @@ public class ThemeFunctionLibrary { .getWindowFormAction(win); } - /** Generate links for CSS files to be included in html head. */ + /** + * Generates the links for CSS files to be included in html head. + * @return + */ static public String getCssLinksForHead() { ApplicationServlet as = (ApplicationServlet) ((Object[]) state.get())[WEBADAPTERSERVLET]; Theme t = as.getThemeSource().getThemeByName(theme()); @@ -451,7 +467,7 @@ public class ThemeFunctionLibrary { themes.add(t); } - // Generate links + // Generates links StringBuffer links = new StringBuffer(); for (int k = themes.size() - 1; k >= 0; k--) { Collection allFiles = ((Theme)themes.get(k)).getFileNames(browser(), Theme.MODE_HTML); @@ -468,7 +484,10 @@ public class ThemeFunctionLibrary { return links.toString(); } - /** Generate links for JavaScript files to be included in html head. */ + /** + * Generates the links for JavaScript files to be included in html head. + * @return + */ static public String getJavaScriptLinksForHead() { ApplicationServlet as = (ApplicationServlet) ((Object[]) state.get())[WEBADAPTERSERVLET]; Theme t = as.getThemeSource().getThemeByName(theme()); @@ -482,7 +501,7 @@ public class ThemeFunctionLibrary { themes.add(t); } - // Generate links + // Generates links StringBuffer links = new StringBuffer(); for (int k = themes.size() - 1; k >= 0; k--) { Collection allFiles = ((Theme) themes.get(k)).getFileNames( @@ -499,7 +518,13 @@ public class ThemeFunctionLibrary { return links.toString(); } - /** Generate JavaScript for updating given window */ + /** + * Generates the JavaScript for updating given window. + * @param application + * @param window + * @param browser + * @return + */ static protected String getWindowRefreshScript(Application application, Window window, WebBrowser browser) { diff --git a/src/com/itmill/toolkit/terminal/web/ThemeSource.java b/src/com/itmill/toolkit/terminal/web/ThemeSource.java index d8089f9f92..dfbfbccb94 100644 --- a/src/com/itmill/toolkit/terminal/web/ThemeSource.java +++ b/src/com/itmill/toolkit/terminal/web/ThemeSource.java @@ -31,60 +31,72 @@ package com.itmill.toolkit.terminal.web; import java.io.InputStream; import java.util.Collection; -/** Interface implemented by theme sources. +/** + * Interface implemented by theme sources. + * * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 */ public interface ThemeSource { - /** Get the name of the ThemeSource. - * @return Name of the theme source. + /** + * Gets the name of the ThemeSource. + * @return the Name of the theme source. */ public String getName(); - /** Get XSL stream for the specified theme and web-browser type. - * Returns the XSL templates, which are used to process the - * UIDL data. Thetype
parameter is used to limit
- * the templates, which are returned based on the theme fileset
- * requirements.
- *
- * This implicitly operates in xslt mode.
- *
- * @param theme Theme, which XSL should be returned
- * @param type The type of the current client.
- * @return Collection of ThemeSource.XSLStream objects.
- * @see Theme
+ /**
+ * Gets the XSL stream for the specified theme and web-browser type.
+ * Returns the XSL templates, which are used to process the
+ * UIDL data. The type
parameter is used to limit
+ * the templates, which are returned based on the theme fileset
+ * requirements.
+ * + * Note : This implicitly operates in xslt mode. + *
+ * @param theme the Theme, which XSL should be returned. + * @param type the type of the current client. + * @return Collection of ThemeSource.XSLStream objects. + * @throws ThemeException If the resource is not found or there was + * some problem finding the resource. + * @see Theme */ public Collection getXSLStreams(Theme theme, WebBrowser type) throws ThemeException; - /** Get the last modification time, used to reload theme on changes. - * @return Last modification time of the theme source. + /** + * Gets the last modification time, used to reload theme on changes. + * @return the Last modification time of the theme source. */ public long getModificationTime(); - /** Get input stream for the resource with the specified resource id. - * @return Stream where the resource can be read. - * @throws ThemeException If the resource is not found or there was - * some problem finding the resource. + /** + * Gets the input stream for the resource with the specified resource id. + * @param resourceId the resource id. + * @return Stream where the resource can be read. + * @throws ThemeException If the resource is not found or there was + * some problem finding the resource. */ public InputStream getResource(String resourceId) throws ThemeException; - /** Get list of themes in the theme source. - * @return List of themes included in the theme source. + /** + * Gets the list of themes in the theme source. + * @return the List of themes included in the theme source. */ public Collection getThemes(); - /** Return Theme instance by name. - * @param name Theme name. - * @return Theme instance matching the name, or null if not found. + /** + * Returns the Theme instance by name. + * @param name the Theme name. + * @return the Theme instance matching the name, or null if not found. */ public Theme getThemeByName(String name); - /** Theme exception. - * Thrown by classes implementing the ThemeSource interface - * if some error occurs during processing. + /** + *ThemeException
is thrown by classes implementing
+ * the ThemeSource
interface if some error occurs during processing.
+ *
* @author IT Mill Ltd.
* @version @VERSION@
* @since 3.0
@@ -93,42 +105,53 @@ public interface ThemeSource {
private static final long serialVersionUID = -7823850742197580285L;
- /** Create new theme exception.
- * @param message Error message.
+ /**
+ * Creates the new theme exception.
+ * @param message the Error message.
*/
public ThemeException(String message) {
super(message);
}
- /** Createa new theme exception.
+ /**
+ * Creates the new theme exception.
*
- * @param message
- * @param e
+ * @param message the error message.
+ * @param cause the cause of the exception.
*/
public ThemeException(String message, Throwable cause) {
super(message,cause);
}
}
- /** Wrapper class for XSL InputStreams */
+ /**
+ * Wrapper class for XSL InputStreams.
+ */
public class XSLStream {
private String id;
private InputStream stream;
-
+
+/**
+ *
+ * @param id
+ * @param stream the input stream.
+ */
public XSLStream(String id, InputStream stream) {
this.id = id;
this.stream = stream;
}
- /** Return id of this stream.
- * @return
+ /**
+ * Returns id of this stream.
+ * @return the id of the stream.
*/
public String getId() {
return id;
}
- /** Return the actual XSL Stream.
- * @return
+ /**
+ * Returns the actual XSL Stream.
+ * @return the XSL Stream.
*/
public InputStream getStream() {
return stream;
diff --git a/src/com/itmill/toolkit/terminal/web/UIDLTransformer.java b/src/com/itmill/toolkit/terminal/web/UIDLTransformer.java
index 225aeac81f..a6e4c21f25 100644
--- a/src/com/itmill/toolkit/terminal/web/UIDLTransformer.java
+++ b/src/com/itmill/toolkit/terminal/web/UIDLTransformer.java
@@ -51,13 +51,14 @@ import javax.xml.transform.ErrorListener;
import javax.xml.transform.SourceLocator;
import javax.xml.transform.OutputKeys;
-/** Class implementing the UIDLTransformer.
+/**
+ * Class implementing the UIDLTransformer.
*
- * The thansformer should not be created directly; it should be contructed
- * using getTransformer() provided by UIDLTransformerFactory.
+ * The transformer should not be created directly; it should be contructed
+ * using getTransformer
provided by UIDLTransformerFactory
.
*
* After the transform has been done, the transformer can be recycled with
- * releaseTransformer() by UIDLTransformerFactory.
+ * releaseTransformer
by UIDLTransformerFactory
.
*
* @author IT Mill Ltd.
* @version @VERSION@
@@ -66,7 +67,9 @@ import javax.xml.transform.OutputKeys;
public class UIDLTransformer {
- /** XSLT factory */
+ /**
+ * XSLT factory.
+ */
protected static javax.xml.transform.TransformerFactory xsltFactory;
static {
xsltFactory = javax.xml.transform.TransformerFactory.newInstance();
@@ -77,28 +80,40 @@ public class UIDLTransformer {
+ "not included in classpath.");
}
- /** Source of the transform containing UIDL */
+ /**
+ * Source of the transform containing UIDL.
+ */
private WebPaintTarget paintTarget;
- /** Holds the type of the transformer. */
+ /**
+ * Holds the type of the transformer.
+ */
private UIDLTransformerType transformerType;
- /** Prepared XSLT transformer for UIDL transformations */
+ /**
+ * Prepared XSLT transformer for UIDL transformations.
+ */
private javax.xml.transform.Transformer uidlTransformer;
- /** Error handled used */
+ /**
+ * Error handled used.
+ */
private TransformerErrorHandler errorHandler;
- /** Theme repository used for late error reporting */
+ /**
+ * Theme repository used for late error reporting.
+ */
private ThemeSource themeSource;
private ApplicationServlet webAdapterServlet;
- /** UIDLTransformer constructor.
- * @param type Type of the transformer
- * @param themes Theme implemented by the transformer
+ /**
+ * UIDLTransformer constructor.
+ * @param type the Type of the transformer.
+ * @param themes the theme implemented by the transformer.
+ * @param webAdapterServlet the Adapter servlet.
* @throws UIDLTransformerException UIDLTransformer exception is thrown,
- * if the transform can not be created.
+ * if the transform can not be created.
*/
public UIDLTransformer(
UIDLTransformerType type,
@@ -109,17 +124,17 @@ public class UIDLTransformer {
this.themeSource = themes;
this.webAdapterServlet = webAdapterServlet;
- // Register error handler
+ // Registers the error handler
errorHandler = new TransformerErrorHandler();
xsltFactory.setErrorListener(errorHandler);
try {
- // Create XML Reader to be used by
+ // Creates XML Reader to be used by
// XSLReader as the actual parser object.
XMLReader parser = XMLReaderFactory.createXMLReader();
- // Create XML reader for concatenating
+ // Creates XML reader for concatenating
// multiple XSL files as one.
XMLReader xmlReader =
@@ -131,23 +146,23 @@ public class UIDLTransformer {
xmlReader.setErrorHandler(errorHandler);
- // Create own SAXSource using a dummy inputSource.
+ // Creates own SAXSource using a dummy inputSource.
SAXSource source = new SAXSource(xmlReader, new InputSource());
uidlTransformer = xsltFactory.newTransformer(source);
if (uidlTransformer != null) {
- // Register transformer error handler
+ // Registers transformer error handler
uidlTransformer.setErrorListener(errorHandler);
- // Ensure HTML output
+ // Ensures HTML output
uidlTransformer.setOutputProperty(OutputKeys.METHOD, "html");
- // Ensure no indent
+ // Ensures no indent
uidlTransformer.setOutputProperty(OutputKeys.INDENT, "no");
}
- // Check if transform itself failed, meaning either
+ // Checks if transform itself failed, meaning either
// UIDL error or error in XSL/T semantics (like XPath)
if (errorHandler.hasFatalErrors()) {
throw new UIDLTransformerException(
@@ -169,16 +184,18 @@ public class UIDLTransformer {
}
}
- /** Get the type of the transformer.
- * @return Type of the transformer.
- */
+ /**
+ * Gets the type of the transformer.
+ * @return the Type of the transformer.
+ */
public UIDLTransformerType getTransformerType() {
return this.transformerType;
}
- /** Attach the output stream to transformer and get corresponding UIDLStream for
+ /**
+ * Attaches the output stream to transformer and get corresponding UIDLStream for
* writing UI description language trough transform to given output.
- * @param variableMap The variable map used for UIDL creation.
+ * @param variableMap the variable map used for UIDL creation.
* @return returns UI description language stream, that can be used for writing UIDL to
* transformer.
*/
@@ -198,9 +215,10 @@ public class UIDLTransformer {
return paintTarget;
}
- /** Reset the transformer, before it can be used again. This also interrupts
+ /**
+ * Resets the transformer, before it can be used again. This also interrupts
* any ongoing transform and thus should not be called before the transform
- * is ready. This is automaticalled by the UIDLTransformFactory, when the UIDLTransformer
+ * is ready. This is automatically called by the UIDLTransformFactory, when the UIDLTransformer
* has been released.
* @see UIDLTransformerFactory#releaseTransformer(UIDLTransformer)
*/
@@ -218,9 +236,11 @@ public class UIDLTransformer {
}
/**
- * Transform the UIDL to HTML and output to the OutputStream.
+ * Transforms the UIDL to HTML and output to the OutputStream.
*
- * @param servletOutputStream - The output stream to render to.
+ * @param outputStream the output stream to render to.
+ * @throws UIDLTransformerException UIDLTransformer exception is thrown,
+ * if the transform can not be created.
*/
public void transform(OutputStream outputStream)
throws UIDLTransformerException {
@@ -236,7 +256,7 @@ public class UIDLTransformer {
org.xml.sax.helpers.XMLReaderFactory.createXMLReader();
reader.setErrorHandler(this.errorHandler);
- // Validate if requested. We validate the UIDL separately,
+ // Validates if requested. We validate the UIDL separately,
// toget the SAXExceptions instead of TransformerExceptions.
// This is required to get the line numbers right.
/* FIXME: Disable due abnormalities in DTD handling.
@@ -261,7 +281,7 @@ public class UIDLTransformer {
errorHandler.getUIDLErrorReport());
}
- // Check if transform itself failed, meaning either
+ // Checks if transform itself failed, meaning either
// UIDL error or error in XSL/T semantics (like XPath)
if (errorHandler.hasFatalErrors()) {
throw new UIDLTransformerException(
@@ -274,7 +294,12 @@ public class UIDLTransformer {
transformerType));
}
}
-
+
+/**
+ *
+ *
+ *
+ */
protected class TransformerErrorHandler
implements ErrorListener, org.xml.sax.ErrorHandler {
@@ -283,21 +308,36 @@ public class UIDLTransformer {
LinkedList fatals = new LinkedList();
Hashtable rowToErrorMap = new Hashtable();
Hashtable errorToRowMap = new Hashtable();
-
+
+/**
+ *
+ * @return
+ */
public boolean hasNoErrors() {
return errors.isEmpty() && warnings.isEmpty() && fatals.isEmpty();
}
-
+
+/**
+ *
+ * @return
+ */
public boolean hasFatalErrors() {
return !fatals.isEmpty();
}
-
+
+/**
+ *
+ *
+ */
public void clear() {
errors.clear();
warnings.clear();
fatals.clear();
}
-
+
+ /**
+ * @see java.lang.Object#toString()
+ */
public String toString() {
return getHTMLErrors("Fatal Errors", fatals)
+ "Tag | @@ -298,11 +340,12 @@ public abstract class AbstractComponent return this.description; } - /** Sets the component's description. See {@link #getDescription()} for + /** + * Sets the component's description. See {@link #getDescription()} for * more information on what the description is. This method will trigger * a {@link com.itmill.toolkit.terminal.Paintable.RepaintRequestEvent RepaintRequestEvent}. * - * @param description new description string for the component + * @param description the new description string for the component. */ public void setDescription(String description) { this.description = description; @@ -317,7 +360,7 @@ public abstract class AbstractComponent return this.parent; } - /* Set the parent component. + /* Sets the parent component. * Don't add a JavaDoc comment here, we use the default documentation * from implemented interface. */ @@ -341,7 +384,8 @@ public abstract class AbstractComponent attach(); } - /** Get the error message for this component. + /** + * Gets the error message for this component. * * @return ErrorMessage containing the description of the error state * of the component or null, if the component contains no errors. Extending @@ -353,20 +397,22 @@ public abstract class AbstractComponent return this.componentError; } - /** Gets the component's error message. + /** + * Gets the component's error message. * @link Terminal.ErrorMessage#ErrorMessage(String, int) * - * @return component's error message + * @return the component's error message. */ public ErrorMessage getComponentError() { return this.componentError; } - /** Sets the component's error message. The message may contain certain + /** + * Sets the component's error message. The message may contain certain * XML tags, for more information see * @link Component.ErrorMessage#ErrorMessage(String, int) * - * @param errorMessage new