Author: julien(a)jboss.com Date: 2007-02-05 12:29:10 -0500 (Mon, 05 Feb 2007) New Revision: 6162 Modified: trunk/core/src/main/org/jboss/portal/core/impl/model/content/AbstractContentHandler.java trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContent.java trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContentHandler.java trunk/core/src/main/org/jboss/portal/core/impl/model/portal/WindowImpl.java trunk/core/src/main/org/jboss/portal/core/model/content/Content.java trunk/core/src/main/org/jboss/portal/core/model/content/ContentType.java trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandler.java trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandlerRegistry.java trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentState.java trunk/core/src/main/org/jboss/portal/test/core/model/content/NullContentHandler.java Log: javadoc for the content handler framework Modified: trunk/core/src/main/org/jboss/portal/core/impl/model/content/AbstractContentHandler.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/impl/model/content/AbstractContentHandler.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/impl/model/content/AbstractContentHandler.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -85,11 +85,11 @@ } } - public void createContent(String contextId, ContentState state) + public void contentCreated(String contextId, ContentState state) { } - public void destroyContent(String contextId, ContentState state) + public void contentDestroyed(String contextId, ContentState state) { } } Modified: trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContent.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContent.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContent.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -76,7 +76,7 @@ // if (currentInstanceRef != null && currentInstanceRef.equals(instanceRef) == false) { - handler.destroyContent(contextId, state); + handler.contentDestroyed(contextId, state); } // Modified: trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContentHandler.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContentHandler.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/impl/model/content/portlet/PortletContentHandler.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -54,7 +54,7 @@ return new PortletContent(this, contextId, state); } - public void destroyContent(String contextId, ContentState state) + public void contentDestroyed(String contextId, ContentState state) { String instanceRef = state.getURI(); Modified: trunk/core/src/main/org/jboss/portal/core/impl/model/portal/WindowImpl.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/impl/model/portal/WindowImpl.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/impl/model/portal/WindowImpl.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -206,7 +206,7 @@ ContentHandler handler = getContentHandler(); // - handler.destroyContent(contextId, this); + handler.contentDestroyed(contextId, this); } private Content getContent() Modified: trunk/core/src/main/org/jboss/portal/core/model/content/Content.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/model/content/Content.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/model/content/Content.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -25,12 +25,17 @@ import org.jboss.portal.common.util.LocalizedString; /** - * The content. + * Defines the base interface for content. * * @author <a href="mailto:julien@jboss.org">Julien Viet</a> * @version $Revision: 1.1 $ */ public interface Content { + /** + * Return a localized display name of the content. + * + * @return the content display name + */ LocalizedString getDisplayName(); } Modified: trunk/core/src/main/org/jboss/portal/core/model/content/ContentType.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/model/content/ContentType.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/model/content/ContentType.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -23,6 +23,8 @@ package org.jboss.portal.core.model.content; /** + * Type safe string for notion of content type. + * * @author <a href="mailto:julien@jboss.org">Julien Viet</a> * @version $Revision: 1.1 $ */ @@ -74,6 +76,13 @@ return value; } + /** + * Factory method to create objects. + * + * @param value the wrapped value + * @return the corresponding content type + * @throws IllegalArgumentException if the string argument is null + */ public static ContentType create(String value) throws IllegalArgumentException { if ("portlet".equals(value)) Modified: trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandler.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandler.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandler.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -25,23 +25,39 @@ import org.jboss.portal.core.model.content.Content; /** + * The content handler act as a factory for <code>Content</code> objects from their state. The interface + * receives also callbacks of the content lifecycle in order to be able to manage additional resources + * related to the content. + * * @author <a href="mailto:julien@jboss.org">Julien Viet</a> * @version $Revision: 1.1 $ */ public interface ContentHandler { /** - * Factory method to create an instance of window content object. + * Factory method that creates an instance of content object. This method is called + * whenever the frameworks needs a runtime representation of the content state which + * can be used at runtime by content clients. + * + * @param contextId the context id in which the state is used + * @param state the state + * @return the content interface implementation */ Content newContent(String contextId, ContentState state); /** - * Life cycle method to signal creation. + * Life cycle method to signal state creation. + * + * @param contextId the context id in which the state is created + * @param state the state */ - void createContent(String contextId, ContentState state); + void contentCreated(String contextId, ContentState state); /** - * Life cycle method to signal destruction. + * Life cycle method to signal state destruction. + * + * @param contextId the context id in which the state is destroyed + * @param state the state */ - void destroyContent(String contextId, ContentState state); + void contentDestroyed(String contextId, ContentState state); } Modified: trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandlerRegistry.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandlerRegistry.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentHandlerRegistry.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -25,29 +25,36 @@ import org.jboss.portal.core.model.content.ContentType; /** + * A registry for content handlers. + * * @author <a href="mailto:julien@jboss.org">Julien Viet</a> * @version $Revision: 1.1 $ */ public interface ContentHandlerRegistry { /** + * Register an handler * - * @param contentType - * @param handler - * @throws IllegalArgumentException + * @param contentType the content type the handler will handle + * @param handler the handler + * @throws IllegalArgumentException if the content type or the handler is null */ void registerHandler(ContentType contentType, ContentHandler handler) throws IllegalArgumentException; /** + * Return an handler for the specified content type or null if it is not found * - * @param contentType - * @return + * @param contentType the content type + * @return the handler + * @throws IllegalArgumentException if the content type is null */ - ContentHandler getHandler(ContentType contentType); + ContentHandler getHandler(ContentType contentType) throws IllegalArgumentException; /** - * - * @param contentType + * Unregister the handler for the specified content type. + * + * @param contentType the content type of the handler to unregister. + * @throws IllegalArgumentException if the content type is null */ - void unregisterHandler(ContentType contentType); + void unregisterHandler(ContentType contentType) throws IllegalArgumentException; } Modified: trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentState.java =================================================================== --- trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentState.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/core/model/content/spi/ContentState.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -23,36 +23,41 @@ package org.jboss.portal.core.model.content.spi; /** + * Represents the state of the content which consist in an URI and a set of properties. + * * @author <a href="mailto:julien@jboss.org">Julien Viet</a> * @version $Revision: 1.1 $ */ public interface ContentState { /** + * Returns the URI value. * - * @return + * @return the URI */ String getURI(); /** - * - * @return + * Set the URI value. */ void setURI(String uri); /** - * Set a content property, the property name must not be null and must start with the litteral 'content.'. + * Set a content property, the property name must be prefixed by the litteral 'content.'. * * @param name the property name * @param value the property value + * @throws IllegalArgumentException if the name is null or is not prefixed by the litteral 'content.'. */ - void setProperty(String name, String value); + void setProperty(String name, String value) throws IllegalArgumentException; /** - * Retrieve a content property + * Return a property of the content state. * * @param name the property name * @return the property value or null if it does not exist + * @throws IllegalArgumentException if the name is null or is not prefixed by the litteral 'content.'. + * @see #setProperty(String, String) */ - String getProperty(String name); + String getProperty(String name) throws IllegalArgumentException; } Modified: trunk/core/src/main/org/jboss/portal/test/core/model/content/NullContentHandler.java =================================================================== --- trunk/core/src/main/org/jboss/portal/test/core/model/content/NullContentHandler.java 2007-02-05 17:12:13 UTC (rev 6161) +++ trunk/core/src/main/org/jboss/portal/test/core/model/content/NullContentHandler.java 2007-02-05 17:29:10 UTC (rev 6162) @@ -25,8 +25,6 @@ import org.jboss.portal.core.model.content.spi.ContentState; import org.jboss.portal.core.model.content.Content; import org.jboss.portal.core.impl.model.content.AbstractContentHandler; -import org.jboss.portal.common.NotYetImplemented; -import org.w3c.dom.Element; /** * @author <a href="mailto:julien@jboss.org">Julien Viet</a> @@ -39,11 +37,11 @@ return new NullContent(contextId, state); } - public void createContent(String contextId, ContentState state) + public void contentCreated(String contextId, ContentState state) { } - public void destroyContent(String contextId, ContentState state) + public void contentDestroyed(String contextId, ContentState state) { } }