From cd52993fba6ada5629ee87ec90a9e8473a8e4bf7 Mon Sep 17 00:00:00 2001 From: "Eric J. Bowersox" Date: Tue, 3 Jun 2003 06:44:55 +0000 Subject: [PATCH] added javadocs to more of the Dynamo interfaces --- .../dynamo/iface/AuditRecordCompose.java | 19 +++++- .../dynamo/iface/AuditRecordFactory.java | 36 ++++++++++- .../dynamo/iface/AuditRecordRetrieval.java | 25 +++++++- .../dynamo/iface/AuditRecordSet.java | 21 ++++++- .../dynamo/iface/Authenticator.java | 35 ++++++++++- .../dynamo/iface/AuthenticatorLookup.java | 18 +++++- .../iface/AuthenticatorRegistration.java | 20 +++++- .../dynamo/iface/BinaryRenderControl.java | 17 +++++- .../dynamo/iface/BinaryRenderer.java | 22 ++++++- .../dynamo/iface/RenderControl.java | 23 ++++++- .../silverwrist/dynamo/iface/Renderer.java | 11 +++- .../dynamo/iface/SelfRenderControl.java | 61 ++++++++++++++++++- .../dynamo/iface/SelfRenderable.java | 7 ++- .../dynamo/iface/TextRenderControl.java | 29 ++++++++- .../dynamo/iface/TextRenderer.java | 22 ++++++- 15 files changed, 349 insertions(+), 17 deletions(-) diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordCompose.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordCompose.java index b9a5d88..fc9467b 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordCompose.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordCompose.java @@ -11,16 +11,33 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ package com.silverwrist.dynamo.iface; +/** + * An extension of {@link com.silverwrist.dynamo.iface.AuditRecord AuditRecord} used for audit records that are + * being composed and written into the database. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuditRecordCompose extends AuditRecord { + /** + * Sets a property on an audit record. A property is like an "argument" to the audit record, + * and may be of any type that can be serialized by the Dynamo PropertySerializer. + * + * @param index Index of the property to set (0-based). Up to 8 properties are supported. + * @param value Value of the property to be set. + */ public void setProperty(int index, Object value); + /** + * Writes this audit record to the database. + */ public void write(); } // end interface AuditRecordCompose diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordFactory.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordFactory.java index 5c41a14..f4171a1 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordFactory.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordFactory.java @@ -11,19 +11,53 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ package com.silverwrist.dynamo.iface; +/** + * An interface which is used to create new audit records for insertion into the database. The new audit records + * have all their basic data items filled in, but none of their optional properties, and are not written to the + * database until their {@link com.silverwrist.dynamo.iface.AuditRecordCompose#write() write()} method is called. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuditRecordFactory { + /** + * Creates a new audit record. + * + * @param r The current {@link com.silverwrist.dynamo.iface.Request Request} we are processing. + * @param user The user that has perfomed the request. + * @param namespace The namespace URI of the audit record type to be written. + * @param name The name of the audit record type to be written. + * @return The new audit record. + */ public AuditRecordCompose createAuditRecord(Request r, DynamoUser user, String namespace, String name); + /** + * Creates a new audit record. + * + * @param r The current {@link com.silverwrist.dynamo.iface.Request Request} we are processing. + * @param user The user that has perfomed the request. + * @param subid The subidentifier value for this audit record. + * @param namespace The namespace URI of the audit record type to be written. + * @param name The name of the audit record type to be written. + * @return The new audit record. + */ public AuditRecordCompose createAuditRecord(Request r, DynamoUser user, int subid, String namespace, String name); + /** + * Creates a new "system-level" audit record, which is normally used only for system-level events. + * + * @param namespace The namespace URI of the audit record type to be written. + * @param name The name of the audit record type to be written. + * @return The new audit record. + */ public AuditRecordCompose createSystemAuditRecord(String namespace, String name); } // end interface AuditRecordFactory diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordRetrieval.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordRetrieval.java index f94de31..73b95c1 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordRetrieval.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordRetrieval.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -20,11 +20,34 @@ package com.silverwrist.dynamo.iface; import java.util.Date; import com.silverwrist.dynamo.except.DatabaseException; +/** + * An interface which is used to retrieve audit records from the database by date and time. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuditRecordRetrieval { + /** + * Retrieves a set of audit records from the database. + * + * @param start_date Starting date/time of the audit records to retrieve. + * @param end_date Ending date/time of the audit records to retrieve. + * @return An {@link com.silverwrist.dynamo.iface.AuditRecordSet} containing the audit records. + * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit records. + */ public AuditRecordSet getAuditRecords(java.util.Date start_date, java.util.Date end_date) throws DatabaseException; + /** + * Retrieves a set of audit records from the database. + * + * @param start_date Starting date/time of the audit records to retrieve. + * @param end_date Ending date/time of the audit records to retrieve. + * @param subid Subidentifier that all retrieved audit records must match. + * @return An {@link com.silverwrist.dynamo.iface.AuditRecordSet} containing the audit records. + * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit records. + */ public AuditRecordSet getAuditRecords(java.util.Date start_date, java.util.Date end_date, int subid) throws DatabaseException; diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordSet.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordSet.java index 38317cc..1225909 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordSet.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuditRecordSet.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -19,10 +19,29 @@ package com.silverwrist.dynamo.iface; import com.silverwrist.dynamo.except.DatabaseException; +/** + * An interface wrapping a set of audit records. This is returned by the methods of the + * {@link com.silverwrist.dynamo.iface.AuditRecordRetrieval AuditRecordRetrieval} interface. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuditRecordSet { + /** + * Returns the number of audit records in this set. + * + * @return The number of audit records in this set. + */ public int getRecordCount(); + /** + * Returns a specific {@link com.silverwrist.dynamo.iface.AuditRecord AuditRecord} from this set. + * + * @param index 0-based index of the audit record to be retrieved. + * @return The audit record. + * @exception com.silverwrist.dynamo.except.DatabaseException If there was a problem retrieving the audit record. + */ public AuditRecord getRecord(int index) throws DatabaseException; } // end interface AuditRecordSet diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/Authenticator.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/Authenticator.java index 9e3b231..ee96661 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/Authenticator.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/Authenticator.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -19,10 +19,43 @@ package com.silverwrist.dynamo.iface; import com.silverwrist.dynamo.except.AuthenticationException; +/** + * The public intrface implemented by all Dynamo authenticators. An authenticator is a piece of + * code that handles two tasks: + *
    + *
  1. The transformation of private authentication data into a format suitable for storing in the database.
    2. + *
  2. The comparison of that private data to private data obtained from the user, and returning whether or not + * it matches.
    3. + *
+ * For example, in the {@link com.silverwrist.dynamo.db.DefaultHashAuthenticator DefaultHashAuthenticator}, the + * former task consists of taking a password and processing it through a secure one-way hash function to produce a + * string which may be stored in the database, and the latter task consists of applying the same function to a user- + * supplied password and comparing the resulting hash value against the one retrieved from the database. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface Authenticator { + /** + * Given a piece of stored authentication data (which has been transformed with + * {@link #processInputData(java.lang.String) processInputData()}) and a piece of user-supplied authentication + * data (which has not), returns whether or not they match. + * + * @param stored_data The stored authentication data from the database. + * @param input_data The input authentication data from the user, + * @return true if the two pieces of data match, false if not. + * @exception com.silverwrist.dynamo.except.AuthenticationException If there was a problem with the authenticator. + */ public boolean authenticate(String stored_data, String input_data) throws AuthenticationException; + /** + * Transforms a piece of input data, such as a password, into a format suitable for storing in the database. + * + * @param input_data Input data to be transformed. + * @return The transformed input data. + * @exception com.silverwrist.dynamo.except.AuthenticationException If there was a problem with the authenticator. + */ public String processInputData(String input_data) throws AuthenticationException; } // end interface Authenticator diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorLookup.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorLookup.java index 8a6666b..3b6a6d3 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorLookup.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorLookup.java @@ -11,14 +11,30 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ package com.silverwrist.dynamo.iface; +/** + * A service interface which permits the retrieval of registered + * {@link com.silverwrist.dynamo.iface.Authenticator Authenticator} objects. Authenticators are identified by + * namespace URI and name. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuthenticatorLookup { + /** + * Retrieves an authenticator that has been registered with the system. + * + * @param method_namespace Namespace URI of the authenticator to be retrieved. + * @param method Name of the authenticator to be retrieved. + * @return The registered {@link com.silverwrist.dynamo.iface.Authenticator Authenticator}, or null + * if no such registered authenticator exists. + */ public Authenticator findAuthenticator(String method_namespace, String method); } // end interface AuthenticatorLookup diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorRegistration.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorRegistration.java index af046e0..8979efc 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorRegistration.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/AuthenticatorRegistration.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -19,8 +19,26 @@ package com.silverwrist.dynamo.iface; import com.silverwrist.dynamo.except.ConfigException; +/** + * A service interface which allows Dynamo components or modules to register an authentication method for + * use by the system. Authenticators are identified by namespace URI and name. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface AuthenticatorRegistration extends AuthenticatorLookup { + /** + * Registers an instance of an {@link com.silverwrist.dynamo.iface.Authenticator Authenticator} with the system. + * + * @param method_namespace Namespace URI of the authentication method to register. + * @param method Name of the authentication method to register. + * @param auth The Authenticator which implements the authentication method. + * @return An instance of {@link com.silverwrist.dynamo.iface.ComponentShutdown ComponentShutdown} whose + * {@link com.silverwrist.dynamo.iface.ComponentShutdown#shutdown() shutdown()} method may be called + * to unregister the authenticator. + * @exception com.silverwrist.dynamo.except.ConfigException If there was an error registering the authenticator. + */ public ComponentShutdown registerAuthenticator(String method_namespace, String method, Authenticator auth) throws ConfigException; diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderControl.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderControl.java index b7ef44a..2d97a7e 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderControl.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderControl.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -22,8 +22,23 @@ import java.io.OutputStream; import javax.servlet.http.HttpServletResponse; import com.silverwrist.dynamo.except.RenderingException; +/** + * The interface implemented by the rendering control object used with + * {@link com.silverwrist.dynamo.iface.BinaryRenderer BinaryRenderer}. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface BinaryRenderControl extends RenderControl { + /** + * Returns an {@link java.io.OutputStream OutputStream} which may be used to output the binary data of the rendering. + * + * @return The output stream. + * @exception java.io.IOException If there was an I/O error getting the output stream. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem getting the output + * stream. + */ public OutputStream getStream() throws IOException, RenderingException; } // end interface BinaryRenderControl diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderer.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderer.java index badc063..a3b0a7f 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderer.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/BinaryRenderer.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -20,8 +20,28 @@ package com.silverwrist.dynamo.iface; import java.io.IOException; import com.silverwrist.dynamo.except.RenderingException; +/** + * An interface implemented by rendering objects which renders the specified object as a binary object + * (such as an image, file attachment, or similar). The rendering object uses the data in the supplied object, as + * well as the methods supplied in the {@link com.silverwrist.dynamo.iface.BinaryRenderControl BinaryRenderControl} + * interface, to generate an output rendering. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface BinaryRenderer extends Renderer { + /** + * Renders the specified object to the output in binary mode. + * + * @param obj The object to be rendered. + * @param control A rendering control object that provides the means to render this object to the output, as + * well as providing "output services" (through the + * {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface) for the + * rendering process to use. + * @exception java.io.IOException If an I/O error occurs while writing the output. + * @exception com.silverwrist.dynamo.except.RenderingException If the rendering process fails. + */ public void render(Object obj, BinaryRenderControl control) throws IOException, RenderingException; } // end interface BinaryRenderer diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderControl.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderControl.java index 6fd387f..fb89375 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderControl.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/RenderControl.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -22,10 +22,31 @@ import java.io.PrintWriter; import javax.servlet.http.HttpServletResponse; import com.silverwrist.dynamo.except.RenderingException; +/** + * The parent interface of rendering control objects, which provide the means by which rendering objects can + * output their renderings to the user's browser. All rendering control objects incorporate a + * {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface, which supplies "output services" + * for the use of the rendering object. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface RenderControl extends ServiceProvider { + /** + * Sets the content type (MIME type) of the output. + * + * @param type The content type to be set. + * @exception com.silverwrist.dynamo.except.RenderingException If there was a problem setting the content type. + */ public void setContentType(String type) throws RenderingException; + /** + * Sets the content length (in bytes) for the output. + * + * @param length The content length to be set. + * @exception com.silverwrist.dynamo.except.RenderingException If there was a problem setting the content length. + */ public void setContentLength(int length) throws RenderingException; } // end interface RenderControl diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/Renderer.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/Renderer.java index c32db21..9ad7347 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/Renderer.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/Renderer.java @@ -11,12 +11,21 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ package com.silverwrist.dynamo.iface; +/** + * An interface which is implemented by all rendering objects, whose function is to take objects returned + * by the processing phase of Dynamo operation and turn them into HTML, which is output to the browser. Rendering + * objects are registered to handle objects of a specific class (and all subclasses thereof, where applicable), + * and are looked up as part of the output phase. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface Renderer { // no methods of its own - used only to identify TextRenderers and BinaryRenderers } // end interface Renderer diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderControl.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderControl.java index b74814f..6d3b344 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderControl.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderControl.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -21,18 +21,77 @@ import java.io.IOException; import com.silverwrist.dynamo.HttpStatusCode; import com.silverwrist.dynamo.except.RenderingException; +/** + * The interface implemented by the rendering control object used by + * {@link com.silverwrist.dynamo.iface.SelfRenderable SelfRenderable} objects.

+ * Note that this interface, unlike the other rendering control interfaces, does not extend + * {@link com.silverwrist.dynamo.iface.RenderControl RenderControl}; however, its + * {@link #getTextRender() getTextRender()} and {@link #getBinaryRender() getBinaryRender()} methods return objects + * that do. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface SelfRenderControl extends ServiceProvider { + /** + * Sends an HTTP status code to the browser. This may be combined with other output methods to write a specific + * message. + * + * @param code The status code to be sent to the browser. + * @exception java.io.IOException If there was an I/O error sending the status code. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the status code + * (for example, if the code has already been set). + */ public void status(HttpStatusCode code) throws RenderingException; + /** + * Causes the browser to redirect to another URL. Sends a "302 Redirect" status code to the browser. + * + * @param location URL to redirect the browser to. + * @exception java.io.IOException If there was an I/O error sending the redirect. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the redirect + * (for example, if text has already been written). + */ public void redirect(String location) throws IOException, RenderingException; + /** + * Sends an HTTP error message to the browser. + * + * @param code The status code to be sent to the browser. + * @exception java.io.IOException If there was an I/O error sending the error message. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the error message + * (for example, if text has already been written). + */ public void error(HttpStatusCode code) throws IOException, RenderingException; + /** + * Sends an HTTP error message to the browser. + * + * @param code The status code to be sent to the browser. + * @param message The error message to be sent to the browser. + * @exception java.io.IOException If there was an I/O error sending the error message. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another error sending the error message + * (for example, if text has already been written). + */ public void error(HttpStatusCode code, String message) throws IOException, RenderingException; + /** + * Returns a rendering control interface suitable for rendering an object in text mode. + * + * @return An instance of {@link com.silverwrist.dynamo.iface.TextRenderControl TextRenderControl}. + * @exception com.silverwrist.dynamo.except.RenderingException If the text rendering interface cannot be returned + * (for instance, if this object is already rendering in binary mode). + */ public TextRenderControl getTextRender() throws RenderingException; + /** + * Returns a rendering control interface suitable for rendering an object in binary mode. + * + * @return An instance of {@link com.silverwrist.dynamo.iface.BinaryRenderControl BinaryRenderControl}. + * @exception com.silverwrist.dynamo.except.RenderingException If the binary rendering interface cannot be returned + * (for instance, if this object is already rendering in text mode). + */ public BinaryRenderControl getBinaryRender() throws RenderingException; } // end interface SelfRenderControl diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderable.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderable.java index ecb859a..d8fcea6 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderable.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/SelfRenderable.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -22,8 +22,9 @@ import com.silverwrist.dynamo.except.RenderingException; /** * An interface implemented on Dynamo output objects to indicate that they are capable of rendering themselves - * to the output. SelfRenderable objects have access to greater capability (afforded them by - * the {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl} interface) than ordinary text or + * to the output, without the use of a {@link com.silverwrist.dynamo.iface.Renderer Renderer} object. + * SelfRenderable objects have access to greater capability (afforded them by the + * {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl} interface) than ordinary text or * binary renderable objects do, and are frequently used to perform "special" operations. * * @author Eric J. Bowersox <erbo@silcom.com> diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderControl.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderControl.java index d50e3b9..56edf4b 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderControl.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderControl.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -21,10 +21,37 @@ import java.io.IOException; import java.io.PrintWriter; import com.silverwrist.dynamo.except.RenderingException; +/** + * The interface implemented by the rendering control object used with + * {@link com.silverwrist.dynamo.iface.TextRenderer TextRenderer}. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface TextRenderControl extends RenderControl { + /** + * Returns a {@link java.io.PrintWriter PrintWriter} which may be used to output the textual data of the rendering. + * + * @return The output writer. + * @exception java.io.IOException If there was an I/O error getting the output writer. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem getting the output + * writer. + */ public PrintWriter getWriter() throws IOException, RenderingException; + /** + * Renders another object to the output at the output's current position. The object to be rendered must be + * renderable in text format, either by means of a registered + * {@link com.silverwrist.dynamo.iface.TextRenderer TextRenderer} object, by means of implementing + * {@link com.silverwrist.dynamo.iface.SelfRenderable SelfRenderable} (which implementation cannot use the + * binary or special rendering methods of {@link com.silverwrist.dynamo.iface.SelfRenderControl SelfRenderControl}), + * or by default (via the object's {@link java.lang.Object#toString() toString()} method). + * + * @param obj The subobject to be rendered. + * @exception java.io.IOException If there was an I/O error rendering the object. + * @exception com.silverwrist.dynamo.except.RenderingException If there was another problem rendering the object. + */ public void renderSubObject(Object obj) throws IOException, RenderingException; } // end interface TextRenderControl diff --git a/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderer.java b/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderer.java index 6ef58f9..9407c1e 100644 --- a/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderer.java +++ b/src/dynamo-framework/com/silverwrist/dynamo/iface/TextRenderer.java @@ -11,7 +11,7 @@ * * The Initial Developer of the Original Code is Eric J. Bowersox , * for Silverwrist Design Studios. Portions created by Eric J. Bowersox are - * Copyright (C) 2002 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. + * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios. All Rights Reserved. * * Contributor(s): */ @@ -20,8 +20,28 @@ package com.silverwrist.dynamo.iface; import java.io.IOException; import com.silverwrist.dynamo.except.RenderingException; +/** + * An interface implemented by rendering objects which renders the specified object as a text object + * (such as an HTML page). The rendering object uses the data in the supplied object, as well as the methods + * supplied in the {@link com.silverwrist.dynamo.iface.TextRenderControl TextRenderControl} interface, to generate + * an output rendering. + * + * @author Eric J. Bowersox <erbo@silcom.com> + * @version X + */ public interface TextRenderer extends Renderer { + /** + * Renders the specified object to the output in text mode. + * + * @param obj The object to be rendered. + * @param control A rendering control object that provides the means to render this object to the output, as + * well as providing "output services" (through the + * {@link com.silverwrist.dynamo.iface.ServiceProvider ServiceProvider} interface) for the + * rendering process to use. + * @exception java.io.IOException If an I/O error occurs while writing the output. + * @exception com.silverwrist.dynamo.except.RenderingException If the rendering process fails. + */ public void render(Object obj, TextRenderControl control) throws IOException, RenderingException; } // end interface TextRenderer