diff options
| author | Jani Laakso <jani.laakso@itmill.com> | 2007-04-12 14:41:25 +0000 |
|---|---|---|
| committer | Jani Laakso <jani.laakso@itmill.com> | 2007-04-12 14:41:25 +0000 |
| commit | 544a4770365be51e26b1b8418f2f4226db5bcb15 (patch) | |
| tree | c5ef61d190d461a3aa789ef8444159f7bd1bd7b3 /src/com/itmill/toolkit/terminal/web | |
| parent | fde5869b30ae8da8ec5d884d3438815e1a63aca1 (diff) | |
| download | vaadin-framework-544a4770365be51e26b1b8418f2f4226db5bcb15.tar.gz vaadin-framework-544a4770365be51e26b1b8418f2f4226db5bcb15.zip | |
Pulled changesets from branches/4.0.0-SRIT into trunk, done by
mohamed.atique@renaissance-it.com. All changes are related to javadocs only.
Merge was done beetween revisions 924:1192.
svn changeset:1212/svn branch:trunk
Diffstat (limited to 'src/com/itmill/toolkit/terminal/web')
27 files changed, 2474 insertions, 1403 deletions
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 <code>true</code> if the request was handled and further processing + * should be suppressed, otherwise <code>false</code>. + * @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("</redirect>"); } - /** - * @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. * * <pre> * Todo: @@ -145,7 +147,8 @@ public class AjaxPaintTarget implements PaintTarget { * </pre> * * @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 * * </pre> + * @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 <code>getUIDL</code> 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 <code>getUIDL</code> + * 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: + * <p> + * 1. Content of <code>THEME_PATH</code> directory (if available). + * </p> + * <p> + * 2. The themes listed in <code>THEME_LIST_FILE</code>. + * </p> + * <p> + * 3. "themesource" application parameter - "ThemeSource" system property. + * </p> + * @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 boolean <code>true</code> if the request was handled and further processing + * should be suppressed, <code>false</code> 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 <code>true</code> if the request was handled and further processing + * should be suppressed, <code>false</code> 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 <code>true</code> if the web adapter is in debug mode. otherwise <code>false</code>. */ 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("<html><head></head><body>"); 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 <code>String</code>. The substring * begins at the specified <code>start</code> and extends to the character * at index <code>end - 1</code> or to the end of the - * <code>String</code> if no such character exists. First the - * characters in the substring are removed and then the specified + * <code>String</code> if no such character exists. + * <p> + * First the characters in the substring are removed and then the specified * <code>String</code> is inserted at <code>start</code>. (The * <code>StringBuffer</code> will be lengthened to accommodate the * specified String if necessary.) + * </p> * <p> * NOTE: This operation is slow. * </p> - * - * @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 if <code>start</code> - * is negative, greater than <code>length()</code>, or - * greater than <code>end</code>. */ 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; -/** <p>Class providing centralized logging services. The logger defines +/** + * <p> + * Class providing centralized logging services. The logger defines * five message types, and provides methods to create messages of those - * types. These types are:</p> + * types. These types are: + * </p> * * <ul> * <li> <code>info</code> - Useful information generated during normal - * operation of the application + * operation of the application. * <li> <code>warning</code> - An error situation has occurred, but the - * operation was able to finish succesfully + * operation was able to finish succesfully. * <li> <code>error</code> - An error situation which prevented the - * operation from finishing succesfully + * operation from finishing succesfully. * <li> <code>debug</code> - Internal information from the application meant - * for developers + * for developers. * <li> <code>exception</code> - 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. * </ul> * - * <p>Currently the class offers logging only to the standard output</p> + * <p> + * Currently the class offers logging only to the standard output. + * </p> * * @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 a <code>warning</code> message. + /** + * Logs the <code>warning</code> message. * - * @param message Message <code>String</code> 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 <code>debug</code> message. + /** + * Logs the <code>debug</code> message. * - * @param message Message <code>String</code> 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 <code>info</code> message. + /** + * Logs an <code>info</code> message. * - * @param message Message <code>String</code> 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 <code>String</code> 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 <code>error</code> message. + /** + * Logs the <code>error</code> message. * - * @param message Message <code>String</code> 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. - - <BR> - <BR> - Copyright (C)2001 Jason Pell. - <BR> - - <PRE> - 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. - <BR> - 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. - <BR> - 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 - <BR> - Email: jasonpell@hotmail.com - Url: http://www.geocities.com/jasonpell - </PRE> - - @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. - <b>Thanks to Mark Latham for the idea and some of the code.</b> 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. + * + * <BR> + * <BR> + * Copyright (C)2001 Jason Pell. + * <BR> + * + * <PRE> + * 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. + * <BR> + * 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. + * <BR> + * 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 + * <BR> + * Email: jasonpell@hotmail.com + * Url: http://www.geocities.com/jasonpell + * </PRE> + * + * @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 <code>getCharArray</code> 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 <code>getEncoding</code> method to allow the use of <code>MultipartRequest</code> with a specific encoding type. All instances + * of MultipartRequest will utilise the static charEncoding variable value, that the <code>setEncoding</code> 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. + * <b>Thanks to Mark Latham for the idea and some of the code.</b> 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. - - <b>Note: </b>Only used for file upload to memory. - */ + * Type constant for the File CONTENTS. + * + * <b>Note: </b>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. - - <p><b>Warning:</b> 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.</p> - */ + * This method should be called on the <code>MultipartRequest</code> itself, not on any + * instances of <code>MultipartRequest</code>, 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. + * + * <p><b>Warning:</b> 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 <code>getEncoding</code> method to convert between bytes and + * strings. If <code>setEncoding</code> method is called by another thread, while the private <code>parse</code> method is + * executing, the method will utilise this new encoding, which may cause serious + * problems.</p> + */ public void setEncoding(String enc) throws UnsupportedEncodingException { if (enc==null || enc.trim()=="") @@ -200,8 +201,9 @@ public class MultipartRequest } /** - Returns the current encoding method. - */ + * Gets the current encoding method. + * @return the encoding method. + */ public String getEncoding() { return charEncoding; @@ -210,10 +212,10 @@ public class MultipartRequest /** * Constructor. * - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</b> * @@ -233,10 +235,10 @@ public class MultipartRequest /** * Constructor. * - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. @@ -259,10 +261,10 @@ public class MultipartRequest * Constructor. * * @param debug A PrintWriter that can be used for debugging. - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * @@ -287,9 +289,9 @@ public class MultipartRequest * Constructor - load into memory constructor * * @param debug A PrintWriter that can be used for debugging. - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. * * @exception IllegalArgumentException If the strContentTypeText does not contain a Content-Type of "multipart/form-data" or the boundary is not found. @@ -313,10 +315,10 @@ public class MultipartRequest * Constructor. * * @param debug A PrintWriter that can be used for debugging. - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. @@ -351,10 +353,10 @@ public class MultipartRequest * Initialise the parser. * * @param debug A PrintWriter that can be used for debugging. - * @param strContentTypeText The "Content-Type" HTTP header value. - * @param intContentLength The "Content-Length" HTTP header value. - * @param in The InputStream to read and parse. - * @param strSaveDirectory The temporary directory to save the file from where they can then be moved to wherever by the + * @param strContentTypeText the "Content-Type" HTTP header value. + * @param intContentLength the "Content-Length" HTTP header value. + * @param in the InputStream to read and parse. + * @param strSaveDirectory the temporary directory to save the file from where they can then be moved to wherever by the * calling process. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * @param intMaxReadBytes Overrides the MAX_BYTES_READ value, to allow arbitrarily long files. @@ -370,7 +372,7 @@ public class MultipartRequest InputStream in, int intMaxReadBytes) throws IllegalArgumentException, IOException { - // save reference to debug stream for later. + // saves reference to debug stream for later. this.debug = debug; if (strContentTypeText!=null && strContentTypeText.startsWith("multipart/form-data") && strContentTypeText.indexOf("boundary=")!=-1) @@ -402,10 +404,13 @@ public class MultipartRequest } /** - Return the value of the strName URLParameter. - If more than one value for a particular Parameter, will return the first. - If an error occurs will return null. - */ + * Gets the value of the strName URLParameter. + * If more than one value for a particular Parameter, will return the first. + * If an error occurs will return null. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return the value of the URL Parameter. + */ public String getURLParameter(String strName) { Object value = htParameters.get(strName); @@ -416,11 +421,14 @@ public class MultipartRequest } /** - Return an enumeration of all values for the strName parameter. - Even if a single value for, will always return an enumeration, although - it may actually be empty if no value was encountered for strName or - it is an invalid parameter name. - */ + * Gets an enumeration of all values for the strName parameter. + * Even if a single value for, will always return an enumeration, although + * it may actually be empty if no value was encountered for strName or + * it is an invalid parameter name. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return the enumeration of all values. + */ public Enumeration getURLParameters(String strName) { Object value = htParameters.get(strName); @@ -436,27 +444,29 @@ public class MultipartRequest } /** - An enumeration of all URL Parameters for the current HTTP Request. - */ + * Gets the enumeration of all URL Parameters for the current HTTP Request. + * @return the enumeration of URl Parameters. + */ public Enumeration getParameterNames() { return htParameters.keys(); } /** - This enumeration will return all INPUT TYPE=FILE parameter NAMES as encountered - during the upload. - */ + * Gets the enumeration of all INPUT TYPE=FILE parameter NAMES as encountered + * during the upload. + * @return + */ public Enumeration getFileParameterNames() { return htFiles.keys(); } /** - Returns the Content-Type of a file. - - @see #getFileParameter(java.lang.String, int) - */ + * Returns the Content-Type of a file. + * + * @see #getFileParameter(java.lang.String, int) + */ public String getContentType(String strName) { // Can cast null, it will be ignored. @@ -464,14 +474,14 @@ public class MultipartRequest } /** - If files were uploaded into memory, this method will retrieve the contents - of the file as a InputStream. - - @return the contents of the file as a InputStream, or null if not file uploaded, - or file uploaded to file system directory. - - @see #getFileParameter(java.lang.String, int) - */ + * If files were uploaded into memory, this method will retrieve the contents + * of the file as a InputStream. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return the contents of the file as a InputStream, or null if not file uploaded, + * or file uploaded to file system directory. + * @see #getFileParameter(java.lang.String, int) + */ public InputStream getFileContents(String strName) { Object obj = getFileParameter(strName, CONTENTS); @@ -482,19 +492,22 @@ public class MultipartRequest } /** - Returns a File reference to the uploaded file. This reference is to the files uploaded location, - and allows you to read/move/delete the file. - - This method is only of use, if files were uploaded to the file system. Will return null if - uploaded to memory, in which case you should use getFileContents(strName) instead. - - @return Returns a null file reference if a call to getFileSize(strName) returns zero or files were - uploaded to memory. - - @see #getFileSize(java.lang.String) - @see #getFileContents(java.lang.String) - @see #getFileSystemName(java.lang.String) - */ + * Returns a File reference to the uploaded file. This + * reference is to the files uploaded location, + * and allows you to read/move/delete the file. + * This method is only of use, if files were uploaded to the + * file system. Will return null if + * uploaded to memory, in which case you should use + * getFileContents(strName) instead. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return a null file reference if a call to + * getFileSize(strName) returns zero or files were + * uploaded to memory. + * @see #getFileSize(java.lang.String) + * @see #getFileContents(java.lang.String) + * @see #getFileSystemName(java.lang.String) + */ public File getFile(String strName) { String filename = getFileSystemName(strName); @@ -506,12 +519,13 @@ public class MultipartRequest } /** - Get the file system basename of an uploaded file. - - @return null if strName not found. - - @see #getFileParameter(java.lang.String, int) - */ + * Gets the file system basename of an uploaded file. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return null if strName not found. + * + * @see #getFileParameter(java.lang.String, int) + */ public String getFileSystemName(String strName) { // Can cast null, it will be ignored. @@ -519,12 +533,13 @@ public class MultipartRequest } /** - Returns the File Size of a uploaded file. - - @return -1 if file size not defined. - - @see #getFileParameter(java.lang.String, int) - */ + * Returns the File Size of a uploaded file. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @return -1 if file size not defined. + * + * @see #getFileParameter(java.lang.String, int) + */ public long getFileSize(String strName) { Object obj = getFileParameter(strName, SIZE); @@ -535,32 +550,30 @@ public class MultipartRequest } /** - Access an attribute of a file upload parameter record. - - @param strName is the form field name, used to upload the file. This identifies - the formfield location in the storage facility. - - @param strFilename This is the FileSystemName of the file - @param type What attribute you want from the File Parameter. - The following types are supported: - MultipartRequest.FILENAME, - MultipartRequest.CONTENT_TYPE, - MultipartRequest.SIZE, - MultipartRequest.CONTENTS - - <p>The getFileSystemName(String strName),getFileSize(String strName),getContentType(String strName), - getContents(String strName) methods all use this method passing in a different type argument.</p> - - <p><b>Note: </b>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.</p> - - @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. + * <p>The getFileSystemName(String strName),getFileSize(String strName),getContentType(String strName), + * getContents(String strName) methods all use this method passing in a different type argument.</p> + * + * <p><b>Note: </b>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.</p> + * + * @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 (read<blockOfBytes.length && new String(blockOfBytes, 0, read, charEncoding).indexOf(this.strBoundary)!=-1) { - // Write the line, minus any line ending bytes. + // Writes the line, minus any line ending bytes. //The secondLineOfBytes will NEVER BE NON-NULL if out==null, so there is no need to included this in the test if(sizeOfSecondArray!=0) { @@ -803,7 +829,7 @@ public class MultipartRequest if (actualLength>0 && out!=null) { out.write(secondLineOfBytes, 0, actualLength); - // Update file size. + // Updates the file size. fileSize+=actualLength; } } @@ -811,12 +837,12 @@ public class MultipartRequest } else { - // Write out previous line. + // Writes the out previous line. //The sizeOfSecondArray will NEVER BE ZERO if out==null, so there is no need to included this in the test if(sizeOfSecondArray!=0) { out.write(secondLineOfBytes, 0, sizeOfSecondArray); - // Update file size. + // Updates the file size. fileSize+=sizeOfSecondArray; } @@ -831,21 +857,21 @@ public class MultipartRequest } } - //Return the number of bytes written to outstream. + //Returns the number of bytes written to outstream. return fileSize; } /** - Read a Multipart section that is a file type. Assumes that the Content-Disposition/Content-Type and blank line - have already been processed. So we read until we hit a boundary, then close file and return. - - @exception IOException if an error occurs writing the file. - - @return the number of bytes read. - */ + * Reads a Multipart section that is a file type. Assumes that the Content-Disposition/Content-Type and blank line + * have already been processed. So we read until we hit a boundary, then close file and return. + * @param in the InputStream to read and parse. + * @param strFilename the FileSystemName of the file. + * @return the number of bytes read. + * @throws IOException if an error occurs writing the file. + */ private long readAndWriteFile(InputStream in, String strFilename) throws IOException { - // Store a reference to this, as we may need to delete it later. + // Stores a reference to this, as we may need to delete it later. File outFile = new File(fileOutPutDirectory, strFilename); BufferedOutputStream out = null; @@ -863,17 +889,18 @@ public class MultipartRequest else { out.close(); - // Delete file as empty. We should be able to delete it, if we can open it! + // Deletes the file as empty. We should be able to delete it, if we can open it! outFile.delete(); } return count; } /** - * If the fileOutPutDirectory wasn't specified, just read the file to memory. + * If the fileOutPutDirectory wasn't specified, just read the file to memory. * - * @param strName - Url parameter this file was loaded under. - * @return contents of file, from which you can garner the size as well. + * @param in the InputStream to read and parse. + * @return contents of file, from which you can garner the size as well. + * @throws IOException if the writing failed due to input/output error. */ private byte[] readFile(InputStream in) throws IOException { @@ -892,12 +919,13 @@ public class MultipartRequest } /** - Returns the length of the line minus line ending. - - @param endOfArray This is because in many cases the byteLine will have garbage data at the end, so we - act as though the actual end of the array is this parameter. If you want to process - the complete byteLine, specify byteLine.length as the endOfArray parameter. - */ + * Gets the length of the line minus line ending. + * @param byteLine + * @param endOfArray This is because in many cases the byteLine will have garbage data at the end, so we + * act as though the actual end of the array is this parameter. If you want to process + * the complete byteLine, specify byteLine.length as the endOfArray parameter. + *@return the length. + */ private static final int getLengthMinusEnding(byte byteLine[], int endOfArray) { if (byteLine==null) @@ -910,7 +938,12 @@ public class MultipartRequest else return endOfArray; } - + + /** + * + * @param buf + * @return + */ private static final int getLengthMinusEnding(StringBuffer buf) { if (buf.length()>=2 && buf.charAt(buf.length()-2) == '\r' && buf.charAt(buf.length()-1) == '\n') @@ -922,17 +955,19 @@ public class MultipartRequest } /** - Reads at most READ_BLOCK blocks of data, or a single line whichever is smaller. - Returns -1, if nothing to read, or we have reached the specified content-length. - - Assumes that bytToBeRead.length indicates the block size to read. - - @return -1 if stream has ended, before a newline encountered (should never happen) OR - we have read past the Content-Length specified. (Should also not happen). Otherwise - return the number of characters read. You can test whether the number returned is less - than bytesToBeRead.length, which indicates that we have read the last line of a file or parameter or - a border line, or some other formatting stuff. - */ + * Reads at most READ_BLOCK blocks of data, or a single line whichever is smaller. + * Returns -1, if nothing to read, or we have reached the specified content-length. + * + * Assumes that bytToBeRead.length indicates the block size to read. + * @param in the InputStream to read and parse. + * @param bytesToBeRead the bytes to be read. + * @return -1 if stream has ended, before a newline encountered (should never happen) OR + * we have read past the Content-Length specified. (Should also not happen). Otherwise + * return the number of characters read. You can test whether the number returned is less + * than bytesToBeRead.length, which indicates that we have read the last line of a file or parameter or + * a border line, or some other formatting stuff. + * @throws IOException if the writing failed due to input/output error. + */ private int readLine(InputStream in, byte[] bytesToBeRead) throws IOException { // Ensure that there is still stuff to read... @@ -956,11 +991,11 @@ public class MultipartRequest } /** - This needs to support the possibility of a / or a \ separator. - - Returns strFilename after removing all characters before the last - occurence of / or \. - */ + * This needs to support the possibility of a / or a \ separator. + * @param strFilename the FileSystemName of the file. + * @return the strFilename after removing all characters before the last + * occurence of / or \. + */ private static final String getBasename (String strFilename) { if (strFilename==null) @@ -977,15 +1012,17 @@ public class MultipartRequest } /** - trimQuotes trims any quotes from the start and end of a string and returns the trimmed string... - */ + * Trims any quotes from the start and end of a string. + * @param strItem + * @return the trimmed string. + */ private static final String trimQuotes (String strItem) { // Saves having to go any further.... if (strItem==null || strItem.indexOf("\"")==-1) return strItem; - // Get rid of any whitespace.. + // Gets the rid of any whitespace.. strItem = strItem.trim(); if (strItem.charAt(0) == '\"') @@ -998,10 +1035,13 @@ public class MultipartRequest } /** - Format of string name=value; name=value; - - If not found, will return null. - */ + * Format of string name=value; name=value; + * If not found, will return null. + * @param strName the form field name, used to upload the file. This identifies + * the formfield location in the storage facility. + * @param strToDecode + * + */ private static final String getValue(String strName, String strToDecode) { strName = strName + "="; @@ -1040,23 +1080,23 @@ public class MultipartRequest * * <p>This method <u><b>does not</b></u> 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. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * - * @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. <b>If you specify <u>null</u> for this parameter, then any files uploaded * will be silently ignored.</B> * @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. + * <p> + * 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. + * </p> + * @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. + * <p> + * The finalize method is never invoked more than once by a Java virtual + * machine for any given object. + * </p> + * @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. + * @return <code>true</code> if terminal is compatible with this rule,otherwise <code>false</code>. + * */ 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 <code>true</code> if terminal is compatible with this rule,otherwise <code>false</code>. + * */ 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 { * <li>Sets the window name</li> * <li>Closes window if it is set to be closed </li> * <ul> - * + * @return */ static public String windowScript() { return generateWindowScript( @@ -194,14 +206,22 @@ public class ThemeFunctionLibrary { (ApplicationServlet) ((Object[]) state.get())[WEBADAPTERSERVLET], browser()); } - + +/** + * + * @param window + * @param app + * @param wa + * @param browser + * @return + */ static protected String generateWindowScript(Window window, Application app, ApplicationServlet wa, WebBrowser browser) { StringBuffer script = new StringBuffer(); LinkedList update = new LinkedList(); - // Add all the windows needto update list + // Adds all the windows needto update list Set dirtyWindows = wa != null ? wa.getDirtyWindows(app) : null; if (dirtyWindows != null) for (Iterator i = dirtyWindows.iterator(); i.hasNext();) { @@ -214,7 +234,7 @@ public class ThemeFunctionLibrary { } } - // Remove all windows that are in frames, of such frame windows that + // Removes all windows that are in frames, of such frame windows that // will be updated anyway Object[] u = update.toArray(); if (u.length > 0 && (window != null && window instanceof FrameWindow)) @@ -241,13 +261,13 @@ public class ThemeFunctionLibrary { } } - // Set window name + // Sets window name if (window != null) { script.append("window.name = \"" + getWindowTargetName(app, window) + "\";\n"); } - // Generate window updatescript + // Generates window updatescript for (Iterator i = update.iterator(); i.hasNext();) { Window w = (Window) i.next(); script.append(getWindowRefreshScript(app, w, browser)); @@ -259,7 +279,7 @@ public class ThemeFunctionLibrary { w.requestRepaintRequests(); } - // Close current window if it is not visible + // Closes current window if it is not visible if (window == null || !window.isVisible()) script.append("window.close();\n"); @@ -268,12 +288,10 @@ public class ThemeFunctionLibrary { /** * Returns an unique target name for a given window name. - * - * @param windowName - * Name of the window. - * @return An unique ID for window target - * @throws IllegalStateException - * If application for window is null. + * @param application + * @param window + * the Name of the window. + * @return An unique ID for window target. */ static public String getWindowTargetName(Application application, Window window) { @@ -287,7 +305,7 @@ public class ThemeFunctionLibrary { /** * Returns an unique target name for current window. * - * @return An unique ID for window target + * @return An unique ID for window target. */ static public String getWindowTargetName() { return getWindowTargetName(application(), window()); @@ -295,10 +313,8 @@ public class ThemeFunctionLibrary { /** * Returns an unique target name for current window. - * - * @return An unique ID for window target - * @throws IllegalStateException - * If application for window is null. + * @param name the name of the window. + * @return An unique ID for window target. */ static public String getWindowTargetName(String name) { Window w = application().getWindow(name); @@ -316,8 +332,8 @@ public class ThemeFunctionLibrary { /** * Returns the country and region code for current application locale. * + * @return the language Country code of the current application locale. * @see Locale#getCountry() - * @return language Country code of the current application locale. */ static public String getLocaleCountryId() { try { @@ -331,8 +347,8 @@ public class ThemeFunctionLibrary { /** * Returns the language code for current application locale. * + * @return the Language code for current application locale. * @see Locale#getLanguage() - * @return language Language code for current application locale. */ static public String getLocaleLanguageId() { try { @@ -344,11 +360,8 @@ public class ThemeFunctionLibrary { } /** - * Get name for week day. - * - * @param Number - * of week day. 0 first day of week. - * @return Name of week day in applications current locale. + * Gets the name of first day of the week. + * @return */ static public int getFirstDayOfWeek() { try { @@ -366,11 +379,11 @@ public class ThemeFunctionLibrary { } /** - * Get name for week day. + * Gets the name for week day. * - * @param Number - * of week day. 0 sunday, 1 monday, ... - * @return Name of week day in applications current locale. + * @param dayOfWeek + * the Number of week day. 0 sunday, 1 monday, ... + * @return the Name of week day in applications current locale. */ static public String getShortWeekday(int dayOfWeek) { try { @@ -383,11 +396,11 @@ public class ThemeFunctionLibrary { } /** - * Get short name for month. + * Gets the short name for month. * - * @param Number - * of month. 0 is January, 1 is February, and so on. - * @return Name of month in applications current locale. + * @param month + * the Number of month. 0 is January, 1 is February, and so on. + * @return the Name of month in applications current locale. */ static public String getShortMonth(int month) { try { @@ -401,11 +414,11 @@ public class ThemeFunctionLibrary { } /** - * Get name for month. + * Gets the name for month. * - * @param Number - * of month. 0 is January, 1 is February, and so on. - * @return Name of month in applications current locale. + * @param month + * the Number of month. 0 is January, 1 is February, and so on. + * @return the Name of month in applications current locale. */ static public String getMonth(int month) { try { @@ -419,14 +432,14 @@ public class ThemeFunctionLibrary { } /** - * Get Form Action URL for the requested window. + * Gets Form Action URL for the requested window. * * <p> * This returns the action for the window main form. This action can be set * through WebApplicationContect setWindowFormAction method.. * </p> * - * @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. The <code>type</code> 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 <code>type</code> parameter is used to limit + * the templates, which are returned based on the theme fileset + * requirements. + * <p> + * Note : This implicitly operates in xslt mode. + * </p> + * @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. + /** + * <code>ThemeException</code> is thrown by classes implementing + * the <code>ThemeSource</code> 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 <code>getTransformer</code> provided by <code>UIDLTransformerFactory</code>. * * After the transform has been done, the transformer can be recycled with - * releaseTransformer() by UIDLTransformerFactory. + * <code>releaseTransformer</code> by <code>UIDLTransformerFactory</code>. * * @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) + "<br />" @@ -306,7 +346,13 @@ public class UIDLTransformer { + getHTMLErrors("Warnings", warnings) + "<br />"; } - + +/** + * + * @param title + * @param l + * @return + */ private String getHTMLErrors(String title, LinkedList l) { String r = ""; r = "<b>" + title + "</b><br />"; @@ -405,12 +451,16 @@ public class UIDLTransformer { } } - /** Gets the formated error report on XSL. */ + /** + * Gets the formated error report on XSL. + * @param themes + * @param type + */ public String getXSLErrorReport( ThemeSource themes, UIDLTransformerType type) { - // Recreate XSL for error reporting + // Recreates the XSL for error reporting StringBuffer readBuffer = new StringBuffer(); try { Collection c = @@ -517,7 +567,10 @@ public class UIDLTransformer { return sb.toString(); } - /** Gets the formated error report on UIDL. */ + /** + * Gets the formated error report on UIDL. + * @return the formatted error report. + */ public String getUIDLErrorReport() { String uidl = "UIDL Source Not Available."; @@ -525,16 +578,16 @@ public class UIDLTransformer { uidl = paintTarget.getUIDL(); StringBuffer sb = new StringBuffer(); - // Print formatted UIDL with errors embedded + // Prints the formatted UIDL with errors embedded int row = 0; int prev = 0; int index = 0; boolean lastLineWasEmpty = false; - // Append error report + // Appends the error report sb.append(toString()); - // Append UIDL + // Appends UIDL sb.append( "<table width=\"100%\" style=\"border-left: 1px solid black; " + "border-right: 1px solid black; border-bottom: " @@ -575,7 +628,11 @@ public class UIDLTransformer { return sb.toString(); } - /** Highlight the XML source. */ + /** + * Highlights the XML source. + * @param xmlSnippet + * @return + */ private String xmlHighlight(String xmlSnippet) { String res = xmlSnippet; @@ -597,7 +654,10 @@ public class UIDLTransformer { return res; } - /** Get the first fatal error. */ + /** + * Gets the first fatal error. + * @return the fatal error. + */ public Throwable getFirstFatalError() { return (Throwable) fatals.iterator().next(); } diff --git a/src/com/itmill/toolkit/terminal/web/UIDLTransformerException.java b/src/com/itmill/toolkit/terminal/web/UIDLTransformerException.java index b147379e8d..a974c2f987 100644 --- a/src/com/itmill/toolkit/terminal/web/UIDLTransformerException.java +++ b/src/com/itmill/toolkit/terminal/web/UIDLTransformerException.java @@ -28,7 +28,8 @@ package com.itmill.toolkit.terminal.web; -/** Exception in transform process. +/** + * Exception in the transform process. * * @author IT Mill Ltd. * @version @VERSION@ @@ -50,8 +51,8 @@ public class UIDLTransformerException extends java.lang.Exception { /** * Constructs an instance of UIDLTransformerException with the specified * detail message. - * @param msg description of exception that occurred - * @param te Transform exception that occurred. + * @param msg the description of exception that occurred. + * @param te the Transform exception that occurred. * @param desc the detailed description. */ public UIDLTransformerException(String msg, Throwable te, String desc) { @@ -59,15 +60,18 @@ public class UIDLTransformerException extends java.lang.Exception { this.transformException = te; this.HTMLDescription = desc; } - /** Returns the detailed description. - * @return Detailed description of exception. + + /** + * Returns the detailed description. + * @return the Detailed description of exception. */ public String getHTMLDescription() { return HTMLDescription; } - /** Returns the nested transform exception that occurred. - * @return Throwable + /** + * Returns the nested transform exception that occurred. + * @return the transform exception */ public Throwable getTransformException() { return transformException; diff --git a/src/com/itmill/toolkit/terminal/web/UIDLTransformerFactory.java b/src/com/itmill/toolkit/terminal/web/UIDLTransformerFactory.java index 8a2fb0cf0a..6bf66dd942 100644 --- a/src/com/itmill/toolkit/terminal/web/UIDLTransformerFactory.java +++ b/src/com/itmill/toolkit/terminal/web/UIDLTransformerFactory.java @@ -35,7 +35,8 @@ import java.util.LinkedList; import java.util.Map; import java.util.Iterator; -/** Class implementing the UIDLTransformer Factory. +/** + * Class implementing the UIDLTransformer Factory. * The factory creates and maintains a pool of transformers that are used * for transforming UIDL to HTML. * @@ -46,25 +47,39 @@ import java.util.Iterator; public class UIDLTransformerFactory { - /** Time between repository modified queries. */ + /** + * Time between repository modified queries. + */ private static final int CACHE_CHECK_INTERVAL_MILLIS = 5 * 1000; - /** The time transformers are cached by default*/ + /** + * The time transformers are cached by default. + */ private static final long DEFAULT_TRANSFORMER_CACHETIME = 60 * 60 * 1000; - /** Maximum number of transformers in use */ + /** + * Maximum number of transformers in use. + */ private int maxConcurrentTransformers = 1; - /** Last time theme modification time was checked */ + /** + * Last time theme modification time was checked. + */ private long lastModificationCheckTime = 0; - /** Last time theme source was modified */ + /** + * Last time theme source was modified. + */ private long themeSourceModificationTime = 0; - /** How long to cache transformers. */ + /** + * How long to cache transformers. + */ private long cacheTime = DEFAULT_TRANSFORMER_CACHETIME; - /** Spool manager thread */ + /** + * Spool manager thread. + */ private SpoolManager spoolManager; private Map transformerSpool = new HashMap(); @@ -73,12 +88,13 @@ public class UIDLTransformerFactory { private int transformerCount = 0; private int transformersInUse = 0; - /** Constructor for transformer factory. + /** + * Constructor for transformer factory. * Method UIDLTransformerFactory. - * @param themeSource Theme source to be used for themes. - * @param webAdapterServlet The Adapter servlet. - * @param maxConcurrentTransformers Maximum number of concurrent themes in use. - * @param cacheTime Time to cache the transformers. + * @param themeSource the Theme source to be used for themes. + * @param webAdapterServlet the Adapter servlet. + * @param maxConcurrentTransformers the Maximum number of concurrent themes in use. + * @param cacheTime the Time to cache the transformers. */ public UIDLTransformerFactory( ThemeSource themeSource, @@ -100,10 +116,12 @@ public class UIDLTransformerFactory { this.spoolManager.start(); } - /** Get new transformer of the specified type - * @param type Type of the requested transformer. - * @param variableMap WebVariable map used by the transformer + /** + * Gets the new transformer of the specified type. + * @param type the Type of the requested transformer. * @return Created new transformer. + * @throws UIDLTransformerException + * if the transform can not be created. */ public synchronized UIDLTransformer getTransformer(UIDLTransformerType type) throws UIDLTransformerException { @@ -116,18 +134,18 @@ public class UIDLTransformerFactory { } } - // Get list of transformers for this type + // Gets the list of transformers for this type TransformerList list = (TransformerList) this.transformerSpool.get(type); - // Check the modification time between fixed intervals + // Checks the modification time between fixed intervals long now = System.currentTimeMillis(); if (now - CACHE_CHECK_INTERVAL_MILLIS > this.lastModificationCheckTime) { this.lastModificationCheckTime = now; - // Check if the theme source has been modified and flush + // Checks if the theme source has been modified and flush // list if necessary long lastmod = this.themeSource.getModificationTime(); if (list != null && this.themeSourceModificationTime < lastmod) { @@ -156,7 +174,7 @@ public class UIDLTransformerFactory { } } else { - // Create new transformer and return it. Transformers are added to + // Creates the new transformer and return it. Transformers are added to // spool when they are released. t = new UIDLTransformer(type, themeSource, webAdapterServlet); transformerCount++; @@ -168,7 +186,7 @@ public class UIDLTransformerFactory { + type); } - // Create new list, if not found + // Creates the new list, if not found if (list == null) { list = new TransformerList(); this.transformerSpool.put(type, list); @@ -182,14 +200,15 @@ public class UIDLTransformerFactory { return t; } - /** Recycle a used transformer back to spool. + /** + * Recycle a used transformer back to spool. * One must guarantee not to use the transformer after it have been released. - * @param transformer UIDLTransformer to be recycled + * @param transformer the UIDLTransformer to be recycled. */ public synchronized void releaseTransformer(UIDLTransformer transformer) { try { - // Reset the transformer before returning it to spool + // Resets the transformer before returning it to spool transformer.reset(); // Recycle the transformer back to spool @@ -222,29 +241,54 @@ public class UIDLTransformerFactory { notifyAll(); } } - + +/** + * + * + * + */ private class TransformerList { private LinkedList list = new LinkedList(); private long lastUsed = 0; - + +/** + * + * @param transformer + */ public void add(UIDLTransformer transformer) { list.add(transformer); } - + +/** + * + * @return + */ public UIDLTransformer removeFirst() { return (UIDLTransformer) ((LinkedList) list).removeFirst(); } - + +/** + * + * @return + */ public boolean isEmpty() { return list.isEmpty(); } - + +/** + * + * @return + */ public int size() { return list.size(); } } - + +/** + * + * + */ private synchronized void removeUnusedTransformers() { long currentTime = System.currentTimeMillis(); HashSet keys = new HashSet(); @@ -269,7 +313,8 @@ public class UIDLTransformerFactory { } } - /** Class for periodically remove unused transformers from memory. + /** + * Class for periodically remove unused transformers from memory. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 @@ -277,12 +322,20 @@ public class UIDLTransformerFactory { protected class SpoolManager extends Thread { long refreshTime; - + +/** + * + * @param refreshTime + */ public SpoolManager(long refreshTime) { super("UIDLTransformerFactory.SpoolManager"); this.refreshTime = refreshTime; } - + + /** + * + * @see java.lang.Thread#run() + */ public void run() { while (true) { try { diff --git a/src/com/itmill/toolkit/terminal/web/UIDLTransformerType.java b/src/com/itmill/toolkit/terminal/web/UIDLTransformerType.java index 3193ab32ff..b42a2c43ce 100644 --- a/src/com/itmill/toolkit/terminal/web/UIDLTransformerType.java +++ b/src/com/itmill/toolkit/terminal/web/UIDLTransformerType.java @@ -28,7 +28,8 @@ package com.itmill.toolkit.terminal.web; -/** Type of the transformer. +/** + * Type of the transformer. * * @author IT Mill Ltd. * @version @VERSION@ @@ -36,13 +37,21 @@ package com.itmill.toolkit.terminal.web; */ public class UIDLTransformerType { - /** Holds value of property webBrowserType. */ + /** + * Holds the value of property webBrowserType. + */ private WebBrowser webBrowser; - /** Holds value of property theme. */ + /** + * Holds the value of property theme. + */ private Theme theme; - /** Creates a new instance of TransformerType */ + /** + * Creates the new instance of TransformerType. + * @param webBrowserType the web browser type. + * @param theme the property theme. + */ public UIDLTransformerType(WebBrowser webBrowserType, Theme theme) { if (webBrowserType == null || theme == null) throw new IllegalArgumentException("WebBrowserType and Theme must be non-null values"); @@ -50,37 +59,48 @@ public class UIDLTransformerType { this.theme = theme; } - /** The hash code of the equal types are the same */ + /** + * Returns the hash code for this string. + * @return the hash code value. + */ public int hashCode() { return this.toString().hashCode(); } - /** Get the web browser type used in the UIDLTransformer of this type. - * @return Web browser type used. + /** + * Gets the web browser type used in the UIDLTransformer of this type. + * @return the Web browser type used. */ public WebBrowser getWebBrowser() { return this.webBrowser; } - /** Get the theme used in the UIDLTransformer of this type. - * @return Theme used. + /** + * Gets the theme used in the UIDLTransformer of this type. + * @return the Theme used. */ public Theme getTheme() { return this.theme; } - /** Two types are equal, if their properties are equal */ + /** + * Two types are equal, if their properties are equal. + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { - // Check that the object are of the same class + // Checks that the object are of the same class if (!(obj.getClass().equals(this.getClass()))) return false; - // Check that the properties of the types are equal + // Checks that the properties of the types are equal return this.toString().equals(obj.toString()); } - /** Textual representation of the UIDLTransformer type */ + /** + * Textual representation of the UIDLTransformer type. + * @see java.lang.Object#toString() + */ public String toString() { return " theme='" + theme.getName() diff --git a/src/com/itmill/toolkit/terminal/web/WebApplicationContext.java b/src/com/itmill/toolkit/terminal/web/WebApplicationContext.java index 7a68acde20..0537cedcdb 100644 --- a/src/com/itmill/toolkit/terminal/web/WebApplicationContext.java +++ b/src/com/itmill/toolkit/terminal/web/WebApplicationContext.java @@ -61,22 +61,25 @@ public class WebApplicationContext implements ApplicationContext { private WeakHashMap formActions = new WeakHashMap(); - /** Create a new Web Application Context. */ + /** + * Creates a new Web Application Context. + * @param session the HTTP session. + */ WebApplicationContext(HttpSession session) { this.session = session; } /** - * Get the form action for given window. - * + * Gets the form action for given window. + * <p> * By default, this action is "", which preserves the current url. Commonly - * this is wanted to be set to <code>application.getUrl().toString()</code> - * or <code>window.getUrl().toString()</code> in order to clean any local + * this is wanted to be set to <code>application.getUrl.toString</code> + * or <code>window.getUrl.toString</code> in order to clean any local * links or parameters set from the action. - * + * </p> * @param window - * Window for which the action is queried - * @return Action to be set into Form action attribute + * the Window for which the action is queried. + * @return the Action to be set into Form action attribute. */ public String getWindowFormAction(Window window) { String action = (String) formActions.get(window); @@ -84,17 +87,17 @@ public class WebApplicationContext implements ApplicationContext { } /** - * Set the form action for given window. - * + * Sets the form action for given window. + * <p> * By default, this action is "", which preserves the current url. Commonly - * this is wanted to be set to <code>application.getUrl().toString()</code> - * or <code>window.getUrl().toString()</code> in order to clean any local + * this is wanted to be set to <code>application.getUrl.toString</code> + * or <code>window.getUrl.toString</code> in order to clean any local * links or parameters set from the action. - * + * </p> * @param window - * Window for which the action is set + * the Window for which the action is set. * @param action - * New action for the window. + * the New action for the window. */ public void setWindowFormAction(Window window, String action) { if (action == null || action == "") @@ -103,9 +106,8 @@ public class WebApplicationContext implements ApplicationContext { formActions.put(window, action); } - /* - * (non-Javadoc) - * + /** + * Gets the application context base directory. * @see com.itmill.toolkit.service.ApplicationContext#getBaseDirectory() */ public File getBaseDirectory() { @@ -117,17 +119,16 @@ public class WebApplicationContext implements ApplicationContext { } /** - * Get the http-session application is running in. + * Gets the http-session application is running in. * - * @return HttpSession this application context resides in + * @return HttpSession this application context resides in. */ public HttpSession getHttpSession() { return session; } - /* - * (non-Javadoc) - * + /** + * Gets the applications in this context. * @see com.itmill.toolkit.service.ApplicationContext#getApplications() */ public Collection getApplications() { @@ -140,36 +141,35 @@ public class WebApplicationContext implements ApplicationContext { } /** - * Get application context for HttpSession. - * - * @return application context for HttpSession. + * Gets the application context for HttpSession. + * @param session the HTTP session. + * @return the application context for HttpSession. */ static public WebApplicationContext getApplicationContext( HttpSession session) { return new WebApplicationContext(session); } - /* - * (non-Javadoc) - * + /** + * Returns <code>true</code> if and only if the argument is not <code>null</code> and is a + * Boolean object that represents the same boolean value as this object. + * @param obj the object to compare with. * @see java.lang.Object#equals(java.lang.Object) */ public boolean equals(Object obj) { return session.equals(obj); } - /* - * (non-Javadoc) - * + /** + * Returns the hash code value . * @see java.lang.Object#hashCode() */ public int hashCode() { return session.hashCode(); } - /* - * (non-Javadoc) - * + /** + * Adds the transaction listener to this context. * @see com.itmill.toolkit.service.ApplicationContext#addTransactionListener(com.itmill.toolkit.service.ApplicationContext.TransactionListener) */ public void addTransactionListener(TransactionListener listener) { @@ -178,9 +178,8 @@ public class WebApplicationContext implements ApplicationContext { this.listeners.add(listener); } - /* - * (non-Javadoc) - * + /** + * Removes the transaction listener from this context. * @see com.itmill.toolkit.service.ApplicationContext#removeTransactionListener(com.itmill.toolkit.service.ApplicationContext.TransactionListener) */ public void removeTransactionListener(TransactionListener listener) { @@ -189,7 +188,11 @@ public class WebApplicationContext implements ApplicationContext { } - /** Notify transaction start */ + /** + * Notifies the transaction start. + * @param application + * @param request the HTTP request. + */ protected void startTransaction(Application application, HttpServletRequest request) { if (this.listeners == null) @@ -200,7 +203,11 @@ public class WebApplicationContext implements ApplicationContext { } } - /** Notify transaction end */ + /** + * Notifies the transaction end. + * @param application + * @param request the HTTP request. + */ protected void endTransaction(Application application, HttpServletRequest request) { if (this.listeners == null) diff --git a/src/com/itmill/toolkit/terminal/web/WebBrowser.java b/src/com/itmill/toolkit/terminal/web/WebBrowser.java index 0ad6ce949e..5f808b7eea 100644 --- a/src/com/itmill/toolkit/terminal/web/WebBrowser.java +++ b/src/com/itmill/toolkit/terminal/web/WebBrowser.java @@ -35,7 +35,8 @@ import java.util.Collection; import java.util.Iterator; import java.util.Locale; -/** Web browser terminal type. +/** + * Web browser terminal type. * * This class implements web browser properties, which declare the features of * the web browser. @@ -48,46 +49,69 @@ public class WebBrowser implements Terminal { private static WebBrowser DEFAULT = new WebBrowser(); - /** Content type */ + /** + * Content type. + */ private String contentType = "text/html; charset=utf-8"; - /** Holds the collection of accepted locales */ + /** + * Holds the collection of accepted locales. + */ private Collection locales = new ArrayList(); - /** Holds value of property browserApplication. */ + /** + * Holds value of property browserApplication. + */ private String browserApplication = null; - /** Should the client side checkking be done. */ + /** + * Should the client side checkking be done. + */ private boolean performClientCheck = true; - /** Holds value for property isClientSideChecked. */ + /** + * Holds value for property isClientSideChecked. + */ private boolean clientSideChecked = false; - /** Holds value of property javaScriptVersion. */ + /** + * Holds value of property javaScriptVersion. + */ private JavaScriptVersion javaScriptVersion = JAVASCRIPT_UNCHECKED; - /** Holds value of property javaEnabled. */ + /** + * Holds value of property javaEnabled. + */ private boolean javaEnabled = false; - /** Holds value of property frameSupport. */ + /** + * Holds value of property frameSupport. + */ private boolean frameSupport = false; - /** Holds value of property markup version. */ + /** + * Holds value of property markup version. + */ private MarkupVersion markupVersion = MARKUP_HTML_3_2; - /** Pixel width of the terminal screen */ + /** + * Pixel width of the terminal screen. + */ private int screenWidth = -1; - /** Pixel height of the terminal screen */ + /** + * Pixel height of the terminal screen. + */ private int screenHeight = -1; private RenderingMode renderingMode = RENDERING_MODE_UNDEFINED; - /** Constuctor with some autorecognition capabilities - * Retrieves all capability information reported in http request headers: + /** + * Constuctor with some autorecognition capabilities + * Retrieves all capability information reported in http request headers: * <ul> - * <li>User web browser (User-Agent)</li> - * <li>Supported locale(s)</li> + * <li>User web browser (User-Agent)</li> + * <li>Supported locale(s)</li> * </ul> */ @@ -98,69 +122,78 @@ public class WebBrowser implements Terminal { public WebBrowser() { } - /** 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() { return ApplicationServlet.DEFAULT_THEME; } - /** Get the name and version of the web browser application. - * + /** + * Gets the name and version of the web browser application. * This is the version string reported by the web-browser in http headers. - * @return Web browser application. + * + * @return the Web browser application. */ public String getBrowserApplication() { return this.browserApplication; } - /** Get the version of the supported Java Script by the browser. + /** + * Gets the version of the supported Java Script by the browser. * - * Null if the Java Script is not supported. - * @return Version of the supported Java Script + * <code>Null</code> if the Java Script is not supported. + * @return the Version of the supported Java Script. */ public JavaScriptVersion getJavaScriptVersion() { return this.javaScriptVersion; } - /** Does the browser support frames ? - * @return True if the browser supports frames, False if not + /** + * Does the browser support frames ? + * @return <code>true</code> if the browser supports frames, otherwise <code>false</code>. */ public boolean isFrameSupport() { return this.frameSupport; } - /** Set the browser frame support - * @param frameSupport True if the browser supports frames, False if not + /** + * Sets the browser frame support. + * @param frameSupport True if the browser supports frames, False if not. */ public void setFrameSupport(boolean frameSupport) { this.frameSupport = frameSupport; } - /** Get the supported markup language. + /** + * Gets the supported markup language. * - * @return Supported markup language + * @return the Supported markup language */ public MarkupVersion getMarkupVersion() { return this.markupVersion; } - /** 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() { return this.screenHeight; } - /** 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() { return this.screenWidth; } - /** Get the default locale requested by the browser. - * @return Default locale + /** + * Gets the default locale requested by the browser. + * @return the Default locale. */ public Locale getDefaultLocale() { if (this.locales.isEmpty()) @@ -168,12 +201,18 @@ public class WebBrowser implements Terminal { return (Locale) this.locales.iterator().next(); } - /** Hash code composed of the properties of the web browser type */ + /** + * Hash code composed of the properties of the web browser type. + * @see java.lang.Object#hashCode() + */ public int hashCode() { return toString().hashCode(); } - /** Test the equality of the properties for two web browser types */ + /** + * Tests the equality of the properties for two web browser types. + * @see java.lang.Object#equals(java.lang.Object) + */ public boolean equals(Object obj) { if (obj != null && obj instanceof WebBrowser) { return toString().equals(obj.toString()); @@ -181,7 +220,9 @@ public class WebBrowser implements Terminal { return false; } - /** Repsent the type of the web browser as string */ + /** + * @see java.lang.Object#toString() + */ public String toString() { String localeString = "["; @@ -192,7 +233,7 @@ public class WebBrowser implements Terminal { } localeString += "]"; - // Return catenation of the properties + // Returns catenation of the properties return "Browser:" + this.browserApplication + ", " @@ -222,34 +263,44 @@ public class WebBrowser implements Terminal { + this.clientSideChecked; } - /** Get preferred content type */ + /** + * Gets the preferred content type. + * @return the content type. + */ public String getContentType() { return contentType; } - /** Check if this type supports also given browser. - * @return true if this type matches the given browser. + /** + * Checks if this type supports also given browser. + * @param browser the browser type. + * @return true if this type matches the given browser. */ public boolean supports(String browser) { return this.getBrowserApplication().indexOf(browser) >= 0; } - /** Check if this type supports given markup language version. - * @return true if this type supports the given markup version. + /** + * Checks if this type supports given markup language version. + * @param html the markup language version. + * @return <code>true</ocde> if this type supports the given markup version,otherwise <code>false</code>. */ public boolean supports(MarkupVersion html) { return this.getMarkupVersion().supports(html); } - /** Check if this type supports given javascript version. - * @param js The javascript version to check for. - * @return true if this type supports the given javascript version. + /** + * Checks if this type supports given javascript version. + * @param js the javascript version to check for. + * @return true if this type supports the given javascript version. */ public boolean supports(JavaScriptVersion js) { return this.getJavaScriptVersion().supports(js); } - /** Parse HTML version from string. + /** + * Parses HTML version from string. + * @param html * @return HTMLVersion instance. */ private MarkupVersion doParseHTMLVersion(String html) { @@ -260,8 +311,10 @@ public class WebBrowser implements Terminal { return MARKUP_UNKNOWN; } - /** Parse JavaScript version from string. - * @return HTMLVersion instance. + /** + * Parses JavaScript version from string. + * @param js the javascript version to check for. + * @return HTMLVersion instance. */ private JavaScriptVersion doParseJavaScriptVersion(String js) { for (int i = 0; i < JAVASCRIPT_VERSIONS.length; i++) { @@ -274,116 +327,135 @@ public class WebBrowser implements Terminal { return JAVASCRIPT_NONE; } - /** Parse HTML version from string. - * @return HTMLVersion instance. + /** + * Parses HTML version from string. + * @param html + * @return the HTMLVersion instance. */ public static MarkupVersion parseHTMLVersion(String html) { return DEFAULT.doParseHTMLVersion(html); } - /** Parse JavaScript version from string. - * @return HTMLVersion instance. + /** + * Parse JavaScript version from string. + * @param js the javascript version to check for. + * @return the HTMLVersion instance. */ public static JavaScriptVersion parseJavaScriptVersion(String js) { return DEFAULT.doParseJavaScriptVersion(js); } - /** Get the client side cheked property. - * Certain terminal features can only be detected at client side. This - * property indicates if the client side detections have been performed - * for this type. - * @return true if client has sent information about its properties. Default false + /** + * Gets the client side cheked property. + * Certain terminal features can only be detected at client side. This + * property indicates if the client side detections have been performed + * for this type. + * @return <code>true</code> if client has sent information about its properties. Default is <code>false</code>. */ public boolean isClientSideChecked() { return this.clientSideChecked; } - /** Set the client side checked property. - * Certain terminal features can only be detected at client side. This - * property indicates if the client side detections have been performed - * for this type. - * @param true if client has sent information about its properties, false otherweise. + /** + * Sets the client side checked property. + * Certain terminal features can only be detected at client side. This + * property indicates if the client side detections have been performed + * for this type. + * @param value true if client has sent information about its properties, false otherweise. */ public void setClientSideChecked(boolean value) { this.clientSideChecked = value; } - /** Should the client features be checked using remote scripts. - * Should the client side terminal feature check be performed. - * @return true if client side checking should be performed for this terminal type. Default false. + /** + * Should the client features be checked using remote scripts. + * Should the client side terminal feature check be performed. + * @return <code>true</code> if client side checking should be performed + * for this terminal type. Default is <code>false</code>. */ public boolean performClientCheck() { return this.performClientCheck; } - /** Should the client features be checked using remote scripts. - * - * @return true if client side checking should be performed for this terminal type. Default false. + /** + * Should the client features be checked using remote scripts. + * @param value + * @return <code>true</code> if client side checking should be performed + * for this terminal type. Default <code>false</code>. */ public void performClientCheck(boolean value) { this.performClientCheck = value; } - /** Check if web browser supports Java. - * @return boolean + /** + * Checks if web browser supports Java. + * @return <code>true<code> if the browser supports java otherwise <code>false</code>. */ public boolean isJavaEnabled() { return javaEnabled; } - /** Returns the locales supported by the web browser. - * @return Collection + /** + * Returns the locales supported by the web browser. + * @return the Collection. */ public Collection getLocales() { return locales; } - /** Sets the browser application. - * This corresponds to User-Agent HTTP header. - * @param browserApplication The browserApplication to set + /** + * Sets the browser application. + * This corresponds to User-Agent HTTP header. + * @param browserApplication the browserApplication to set. */ public void setBrowserApplication(String browserApplication) { this.browserApplication = browserApplication; } - /** Sets the default content type. - * Default is <code>text/html</code> - * @param contentType The contentType to set + /** + * Sets the default content type. + * Default is <code>text/html</code> + * @param contentType the contentType to set. */ public void setContentType(String contentType) { this.contentType = contentType; } - /** Sets the java enabled property. - * @param javaEnabled The javaEnabled to set + /** + * Sets the java enabled property. + * @param javaEnabled the javaEnabled to set. */ public void setJavaEnabled(boolean javaEnabled) { this.javaEnabled = javaEnabled; } - /**Sets the JavaScript version. - * @param javaScriptVersion The JavaScript version to set + /** + * Sets the JavaScript version. + * @param javaScriptVersion the JavaScript version to set. */ public void setJavaScriptVersion(JavaScriptVersion javaScriptVersion) { this.javaScriptVersion = javaScriptVersion; } - /** Sets the markup language version. - * @param markupVersion ersion The markup language version to set + /** + * Sets the markup language version. + * @param markupVersion the markup language version to set. */ public void setMarkupVersion(MarkupVersion markupVersion) { this.markupVersion = markupVersion; } - /** Sets the screen height. - * @param screenHeight The screen height to set in pixels. + /** + * Sets the screen height. + * @param screenHeight the screen height to set in pixels. */ public void setScreenHeight(int screenHeight) { this.screenHeight = screenHeight; } - /** Sets the screen width. - * @param screenWidth The screenWidth to set in pixels. + /** + * Sets the screen width. + * @param screenWidth the screenWidth to set in pixels. */ public void setScreenWidth(int screenWidth) { this.screenWidth = screenWidth; @@ -400,6 +472,9 @@ public class WebBrowser implements Terminal { private int order; /** + * Returns <code>true</code> if and only if the argument is not <code>null</code> and is a + * Boolean object that represents the same boolean value as this object. + * @param obj the object to compare with. * @see java.lang.Object#equals(Object) */ public boolean equals(Object obj) { @@ -414,14 +489,21 @@ public class WebBrowser implements Terminal { public String toString() { return name; } - + +/** + * + * @param name + * @param order + */ private MarkupVersion(String name, int order) { this.name = name; this.order = order; } - /** Check compability with other HTML version. - * @return true if this is compatible with the other, false otherwise + /** + * Checks the compability with other HTML version. + * @param other the HTML version. + * @return <code>true</code> if this is compatible with the other, otherwise <code>false</code>. */ public boolean supports(MarkupVersion other) { return (this.order >= other.order); @@ -484,16 +566,23 @@ public class WebBrowser implements Terminal { public String toString() { return name; } - + +/** + * + * @param name + * @param order + */ private JavaScriptVersion(String name, int order) { this.name = name; this.order = order; } - /** Check compability with other JavaScript version. - * Use this like: - * <code>boolean isEcma = someVersion.supports(ECMA_262);</code> - * @return true if this supports the other, false otherwise + /** + * Checks the compability with other JavaScript version. + * Use this like: + * <code>boolean isEcma = someVersion.supports(ECMA_262);</code> + * @param other the java script version. + * @return <code>true</code> if this supports the other, otherwise <code>false</code>. */ public boolean supports(JavaScriptVersion other) { @@ -594,16 +683,16 @@ public class WebBrowser implements Terminal { public static final RenderingMode RENDERING_MODE_AJAX = DEFAULT.new RenderingMode(); /** - * Gets current rendering mode - * @return current rendering mode + * Gets the current rendering mode. + * @return the current rendering mode. */ public RenderingMode getRenderingMode() { return renderingMode; } /** - * Sets current rendering mode - * @param renderingMode + * Sets the current rendering mode. + * @param renderingMode the rendering mode. */ public void setRenderingMode(RenderingMode renderingMode) { this.renderingMode = renderingMode; diff --git a/src/com/itmill/toolkit/terminal/web/WebBrowserProbe.java b/src/com/itmill/toolkit/terminal/web/WebBrowserProbe.java index cbe61d0474..835705082c 100644 --- a/src/com/itmill/toolkit/terminal/web/WebBrowserProbe.java +++ b/src/com/itmill/toolkit/terminal/web/WebBrowserProbe.java @@ -37,7 +37,7 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpSession; /** - * The WebBrowserProbe uses JavaScript to determine the capabilities of the + * The <code>WebBrowserProbe</code> uses JavaScript to determine the capabilities of the * client browser. * * @author IT Mill Ltd. @@ -52,8 +52,8 @@ public class WebBrowserProbe { private static final String CLIENT_TYPE = "wa_browser"; /** - * Return the terminal type from the given session. - * + * Returns the terminal type from the given session. + * @param session the HTTP session. * @return WebBrowser instance for the given session. */ public static WebBrowser getTerminalType(HttpSession session) { @@ -63,8 +63,9 @@ public class WebBrowserProbe { } /** - * Set the terminal type for the given session. - * + * Sets the terminal type for the given session. + * @param session the HTTP session. + * @param terminal the web browser. * @return WebBrowser instance for the given session. */ public static void setTerminalType(HttpSession session, WebBrowser terminal) { @@ -73,13 +74,15 @@ public class WebBrowserProbe { } /** - * Handle client checking. + * Handles the client checking. * * @param request - * The HTTP request to process. - * @param response - * HTTP response to write to. - * @return true if response should include a probe script + * the HTTP request to process. + * @param parameters + * the Parameters to be used as defaults. + * @return <code>true</code> if response should include a probe script,otherwise <code>false</code>. + * @throws ServletException if an exception has occurred that interferes with the + * servlet's normal operation. */ public static boolean handleProbeRequest(HttpServletRequest request, Map parameters) throws ServletException { @@ -106,11 +109,11 @@ public class WebBrowserProbe { } - // Create new type based on client parameters + // Creates new type based on client parameters browser = probe(browser, request, parameters); setTerminalType(s, browser); - // Set client as checked if parameters were found + // Sets client as checked if parameters were found if (parameters.containsKey("wa_clientprobe")) { String val = ((String[]) parameters.get("wa_clientprobe"))[0]; browser.setClientSideChecked(val != null && "1".equals(val)); @@ -122,10 +125,10 @@ public class WebBrowserProbe { } /** - * Determine versions based on user agent string. + * Determines versions based on user agent string. * * @param agent - * HTTP User-Agent request header. + * the HTTP User-Agent request header. * @return new WebBrowser instance initialized based on agent features. */ public static WebBrowser probe(String agent) { @@ -268,15 +271,15 @@ public class WebBrowserProbe { } /** - * Create new instance of WebBrowser by initializing the values based on + * Creates new instance of WebBrowser by initializing the values based on * user request. * * @param browser - * The browser to be updated. If null a new instance is created. + * the browser to be updated. If null a new instance is created. * @param request - * Request to be used as defaults. + * the Request to be used as defaults. * @param params - * Parameters to be used as defaults. + * the Parameters to be used as defaults. * @return new WebBrowser instance initialized based on request parameters. */ public static WebBrowser probe(WebBrowser browser, diff --git a/src/com/itmill/toolkit/terminal/web/WebPaintTarget.java b/src/com/itmill/toolkit/terminal/web/WebPaintTarget.java index 7c4d58652b..27b5c7e93d 100644 --- a/src/com/itmill/toolkit/terminal/web/WebPaintTarget.java +++ b/src/com/itmill/toolkit/terminal/web/WebPaintTarget.java @@ -41,7 +41,8 @@ import com.itmill.toolkit.terminal.VariableOwner; import java.util.Stack; -/** User Interface Description Language Target. +/** + * User Interface Description Language Target. * @author IT Mill Ltd. * @version @VERSION@ * @since 3.0 @@ -67,9 +68,8 @@ public class WebPaintTarget implements PaintTarget { private boolean mSuppressOutput = false; - /** Create a new XMLPrintWriter, without automatic line flushing. - * - * + /** + * Creates a new XMLPrintWriter, without automatic line flushing. * @param out A character-output stream. */ public WebPaintTarget( @@ -85,23 +85,23 @@ public class WebPaintTarget implements PaintTarget { // Target theme this.theme = theme; - // Set the variable map + // Sets the variable map this.variableMap = variableMap; - // Set the target for UIDL writing + // Sets the target for UIDL writing this.uidlBuffer = new StringBuffer(); - // Set the target for TAG data + // Sets the target for TAG data this.tagBuffer = new StringBuffer(); // Initialize tag-writing 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("uidl"); // Name of the active theme @@ -109,7 +109,8 @@ public class WebPaintTarget implements PaintTarget { } - /** Ensures that the currently open element tag is closed. + /** + * Ensures that the currently open element tag is closed. */ private void ensureClosedTag() { if (mTagArgumentListOpen) { @@ -118,13 +119,15 @@ public class WebPaintTarget implements PaintTarget { append(tagBuffer); } } - /** Print element start tag. + /** + * Prints element start tag. * * <pre>Todo: * Checking of input values * </pre> * - * @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 { @@ -150,19 +153,21 @@ public class WebPaintTarget implements PaintTarget { mTagArgumentListOpen = true; } - /** Print element end tag. + /** + * Prints element end tag. * * If the parent tag is closed before * every child tag is closed a PaintException is raised. * - * @param tag The name of the end tag + * @param tagName 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: if (tagName == null) throw new NullPointerException(); - //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."); @@ -177,11 +182,11 @@ public class WebPaintTarget implements PaintTarget { + lastTag + "'."); - // Make sure that the open start tag is closed before + // Makes sure that the open start tag is closed before // anything is written. ensureClosedTag(); - //Write the end (closing) tag + //Writes the end (closing) tag append("</" + lastTag + "\n>"); // NOTE: We re-enable the output (if it has been disabled) @@ -190,9 +195,10 @@ public class WebPaintTarget implements PaintTarget { mSuppressOutput = false; } - /** Append data into UIDL output buffer. + /** + * Appends data into UIDL output buffer. * - * @param data String to be appended. + * @param data the String to be appended. */ private void append(String data) { if (!mSuppressOutput) { @@ -200,9 +206,10 @@ public class WebPaintTarget implements PaintTarget { } } - /** Append data into UIDL output buffer. + /** + * Appends data into UIDL output buffer. * - * @param data StringBuffer to be appended. + * @param data the StringBuffer to be appended. */ private void append(StringBuffer data) { if (!mSuppressOutput) { @@ -210,8 +217,9 @@ public class WebPaintTarget implements PaintTarget { } } - /** Substitute the XML sensitive characters with predefined XML entities. - * + /** + * Substitutes the XML sensitive characters with predefined XML entities. + * @param xml * @return A new string instance where all occurrences of XML sensitive * characters are substituted with entities. */ @@ -221,8 +229,9 @@ public class WebPaintTarget implements PaintTarget { return escapeXML(new StringBuffer(xml)).toString(); } - /** Substitute the XML sensitive characters with predefined XML entities. - * @param xml the String to be substituted + /** + * Substitutes the XML sensitive characters with predefined XML entities. + * @param xml the String to be substituted. * @return A new StringBuffer instance where all occurrences of XML * sensitive characters are substituted with entities. * @@ -245,8 +254,9 @@ public class WebPaintTarget implements PaintTarget { return result; } - /** Substitute a XML sensitive character with predefined XML entity. - * @param c Character to be replaced with an entity. + /** + * Substitutes a XML sensitive character with predefined XML entity. + * @param c 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. */ @@ -267,12 +277,14 @@ public class WebPaintTarget implements PaintTarget { } } - /** Print XML. + /** + * Prints XML. * * Writes pre-formatted XML to stream. Well-formness of XML is checked. * <pre> * TODO: XML checking should be made * </pre> + * @param str */ private void print(String str) { // In case of null data output nothing: @@ -287,18 +299,23 @@ public class WebPaintTarget implements PaintTarget { append(str); } - /** Print XML-escaped text. + /** + * Prints XML-escaped text. + * @param str + * @throws PaintException if the paint operation failed. * */ public void addText(String str) throws PaintException { addUIDL(escapeXML(str)); } - /** 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 + * @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 { @@ -312,11 +329,13 @@ public class WebPaintTarget implements PaintTarget { } } - /** 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 + * @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 { @@ -351,34 +370,37 @@ public class WebPaintTarget implements PaintTarget { } - /** 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 { addAttribute(name, String.valueOf(value)); } - /** Adds a long attribute to component. + /** + * 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 { addAttribute(name, String.valueOf(value)); } - /** 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 { // In case of null data output nothing: @@ -396,11 +418,12 @@ public class WebPaintTarget implements PaintTarget { tagBuffer.append(" " + name + "=\"" + escapeXML(value) + "\""); } - /** 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 { @@ -412,11 +435,12 @@ public class WebPaintTarget implements PaintTarget { endTag("string"); } - /** 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 { @@ -428,11 +452,12 @@ public class WebPaintTarget implements PaintTarget { endTag("integer"); } - /** 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 { @@ -444,11 +469,12 @@ public class WebPaintTarget implements PaintTarget { endTag("boolean"); } - /** 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 { @@ -461,11 +487,12 @@ public class WebPaintTarget implements PaintTarget { endTag("array"); } - /** 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 { @@ -477,10 +504,15 @@ public class WebPaintTarget implements PaintTarget { endTag("uploadstream"); } - /** Print single text section. - * + /** + * Prints the single text section. + * <p> * Prints full text section. The section data is escaped from XML tags and * surrounded by XML start and end-tags. + * </p> + * @param sectionTagName the name of the tag. + * @param sectionData the section data. + * @throws PaintException if the paint operation failed. */ public void addSection(String sectionTagName, String sectionData) throws PaintException { @@ -489,7 +521,11 @@ public class WebPaintTarget 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 @@ -505,7 +541,9 @@ public class WebPaintTarget implements PaintTarget { append(xml); } - /** Add XML section with namespace + /** + * Adds XML section with namespace. + * * @see com.itmill.toolkit.terminal.PaintTarget#addXMLSection(String, String, String) */ public void addXMLSection( @@ -514,7 +552,7 @@ public class WebPaintTarget implements PaintTarget { String namespace) throws PaintException { - //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."); @@ -522,7 +560,7 @@ public class WebPaintTarget implements PaintTarget { if (namespace != null) addAttribute("xmlns", namespace); - // Close that starting tag + // Closes that starting tag ensureClosedTag(); if (sectionData != null) @@ -530,9 +568,11 @@ public class WebPaintTarget implements PaintTarget { endTag(sectionTagName); } - /** 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 <code>getUIDL</code> + * can be called. + * @return the UIDL. */ public String getUIDL() { if (this.closed) { @@ -541,13 +581,15 @@ public class WebPaintTarget implements PaintTarget { throw new IllegalStateException("Tried to read UIDL from open PaintTarget"); } - /** Close the paint target. - * Paint target must be closed before the getUIDL() - * cn be called. + /** + * Closes the paint target. + * Paint target must be closed before the <code>getUIDL</code> + * 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) { @@ -556,18 +598,23 @@ public class WebPaintTarget implements PaintTarget { } } - /** 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. <p> If the Paintable is found in cache and this + * the startTag method. + * <p> + * 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. - * </p><b>Note:</b> Web adapter does not currently implement caching and + * </p> + * <b>Note:</b> Web adapter does not currently implement caching and * this function always returns false. - * @param paintable The paintable to start - * @param tagName The name of the start tag + * @param paintable the paintable to start. + * @param tag the name of the start tag. * @return false + * @throws PaintException if the paint operation failed. * @see com.itmill.toolkit.terminal.PaintTarget#startTag(Paintable, String), * #startTag(String) * @since 3.1 @@ -578,8 +625,10 @@ public class WebPaintTarget implements PaintTarget { return false; } - /** 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 */ public void addCharacterData(String text) throws PaintException { diff --git a/src/com/itmill/toolkit/terminal/web/XSLReader.java b/src/com/itmill/toolkit/terminal/web/XSLReader.java index 436886a095..cf0c94fe22 100644 --- a/src/com/itmill/toolkit/terminal/web/XSLReader.java +++ b/src/com/itmill/toolkit/terminal/web/XSLReader.java @@ -46,7 +46,8 @@ import org.xml.sax.SAXNotSupportedException; import org.xml.sax.SAXParseException; import org.xml.sax.XMLReader; -/** Class implementing XMLReader for the UIDLTransformer. +/** + * Class implementing XMLReader for the UIDLTransformer. * * @author IT Mill Ltd. * @version @VERSION@ @@ -118,8 +119,9 @@ public class XSLReader implements XMLReader, ContentHandler { this.streams = streams; } - /** Parse all streams given for constructor parameter. - * The input parameter is ignored. + /** + * Parses all streams given for constructor parameter. + * The input parameter is ignored. * @see org.xml.sax.XMLReader#parse(InputSource) */ public synchronized void parse(InputSource input) @@ -140,6 +142,7 @@ public class XSLReader implements XMLReader, ContentHandler { handler.endElement(xslNamespace, "stylesheet", "xsl:stylesheet"); handler.endDocument(); } + /** * @see org.xml.sax.ContentHandler#endElement(String, String, String) */ @@ -257,19 +260,22 @@ public class XSLReader implements XMLReader, ContentHandler { handler.startPrefixMapping(prefix, uri); } - /** Override the default content handler. + /** + * Overrides the default content handler. * @see org.xml.sax.XMLReader#getContentHandler() */ public ContentHandler getContentHandler() { return this.handler; } - /** Override the default content handler. + /** + * Overrides the default content handler. * @see org.xml.sax.XMLReader#setContentHandler(ContentHandler) */ public void setContentHandler(ContentHandler handler) { this.handler = handler; } + /** * @see org.xml.sax.XMLReader#getDTDHandler() */ @@ -307,7 +313,8 @@ public class XSLReader implements XMLReader, ContentHandler { return reader.getProperty(name); } - /** Override the parse. + /** + * Overrides the parse. * @see org.xml.sax.XMLReader#parse(String) */ public void parse(String systemId) throws IOException, SAXException { @@ -354,7 +361,11 @@ public class XSLReader implements XMLReader, ContentHandler { public class AttributeMapper implements Attributes { private Attributes original; - + + /** + * + * @param originalAttributes + */ public AttributeMapper(Attributes originalAttributes) { original = originalAttributes; } @@ -478,31 +489,53 @@ public class XSLReader implements XMLReader, ContentHandler { public class XSLStreamLocator implements Locator { private String id; - + +/** + * + * @param id + */ public XSLStreamLocator(String id) { this.id = id; } - + + /** + * + * @see org.xml.sax.Locator#getPublicId() + */ public String getPublicId() { return streamLocator.getPublicId(); } - + + /** + * + * @see org.xml.sax.Locator#getSystemId() + */ public String getSystemId() { return streamLocator.getSystemId()+""+id; } - + /** + * + * @see org.xml.sax.Locator#getLineNumber() + */ public int getLineNumber() { return streamLocator.getLineNumber(); } - + public int getCombinedLineNumber() { return streamLocator.getLineNumber()+streamStartLineNumber; - } - + } + + /** + * @see org.xml.sax.Locator#getColumnNumber() + */ public int getColumnNumber() { return streamLocator.getColumnNumber(); } - + + /** + * Gets the id. + * @return the id . + */ public String getId() { return id; } @@ -511,11 +544,18 @@ public class XSLReader implements XMLReader, ContentHandler { public class SAXStreamErrorHandler implements ErrorHandler { private ErrorHandler handler; - + +/** + * + * @param origHandler + */ SAXStreamErrorHandler(ErrorHandler origHandler) { this.handler = origHandler; } - + + /** + * @see org.xml.sax.ErrorHandler#warning(org.xml.sax.SAXParseException) + */ public void warning(SAXParseException exception) throws SAXException { handler.warning( new SAXParseException( @@ -523,7 +563,10 @@ public class XSLReader implements XMLReader, ContentHandler { locator, exception)); } - + + /** + * @see org.xml.sax.ErrorHandler#error(org.xml.sax.SAXParseException) + */ public void error(SAXParseException exception) throws SAXException { handler.error( new SAXParseException( @@ -531,7 +574,10 @@ public class XSLReader implements XMLReader, ContentHandler { locator, exception)); } - + + /** + * @see org.xml.sax.ErrorHandler#fatalError(org.xml.sax.SAXParseException) + */ public void fatalError(SAXParseException exception) throws SAXException { handler.fatalError( |