Author: julien(a)jboss.com Date: 2008-03-28 17:23:51 -0400 (Fri, 28 Mar 2008) New Revision: 10410 Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIModel.java branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIObject.java branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPort.java branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortContext.java branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortScope.java Log: javadoc for new model impl Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIModel.java =================================================================== --- branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIModel.java 2008-03-28 20:57:24 UTC (rev 10409) +++ branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIModel.java 2008-03-28 21:23:51 UTC (rev 10410) @@ -23,14 +23,28 @@ package org.jboss.portal.presentation.model2; /** + * The user interface model + * * @author <a href="mailto:julien@jboss-portal.org">Julien Viet</a> * @version $Revision: 630 $ */ public interface UIModel { + /** + * The root id of the model. + * + * @return the root id + */ String getRootId(); + /** + * Creates a viewport from the specified context and scope. + * + * @param context the context + * @param scope the scope + * @return the viewport + */ ViewPort createViewPort(ViewPortContext context, ViewPortScope scope); } Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIObject.java =================================================================== --- branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIObject.java 2008-03-28 20:57:24 UTC (rev 10409) +++ branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/UIObject.java 2008-03-28 21:23:51 UTC (rev 10410) @@ -27,6 +27,9 @@ import java.util.Set; /** + * A wrapper of a structural object. The main goal of this object is to let the viewport add custom payload + * in addition of the structural state. + * * @author <a href="mailto:julien@jboss-portal.org">Julien Viet</a> * @version $Revision: 630 $ */ Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPort.java =================================================================== --- branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPort.java 2008-03-28 20:57:24 UTC (rev 10409) +++ branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPort.java 2008-03-28 21:23:51 UTC (rev 10410) @@ -23,6 +23,11 @@ package org.jboss.portal.presentation.model2; /** + * A viewport is a view of a subset of the structural state presented by the structural state context. + * It does not provide access to the information but rather provides a way to populate a viewport context + * using a viewport scope because the presentation client implementation is the party responsible for + * defining the scope of the view port as well as the storage of the viewport informations. + * * @author <a href="mailto:julien@jboss-portal.org">Julien Viet</a> * @version $Revision: 630 $ */ @@ -30,7 +35,11 @@ { /** - * Performs a refresh operation. + * Performs a refresh operation. The viewport uses the viewport scope object to navigate the structural + * state and perform updates to the viewport scope. If the viewport context is not yet populated, the + * refresh operation populates the context with the viewport defined the viewport scope. If the viewport + * already contains structural information then the viewport proceeds to a merge of the actual state held + * by the viewport context and the refreshed state provided by the structural state context. */ void refresh(); Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortContext.java =================================================================== --- branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortContext.java 2008-03-28 20:57:24 UTC (rev 10409) +++ branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortContext.java 2008-03-28 21:23:51 UTC (rev 10410) @@ -23,26 +23,73 @@ package org.jboss.portal.presentation.model2; /** + * This interface defines read-write access to the structural information of a viewport. + * * @author <a href="mailto:julien@jboss-portal.org">Julien Viet</a> * @version $Revision: 630 $ */ public interface ViewPortContext { + /** + * Returns the specified object or null if it does not exist + * + * @param objectId the object id + * @return the specified object + */ UIObject getObject(String objectId); - void removeObject(String objectId); + /** + * Populate the context with the specified object. + * + * @param object the object + */ + void addObject(UIObject object); + /** + * Signals the context that the object state has been updated. + * + * @param objectId the object id + */ void updateObject(String objectId); - void addObject(UIObject object); + /** + * Removes the specified object from the context. + * + * @param objectId the object id + */ + void removeObject(String objectId); + /** + * Initialize the children of a specified object. + * + * @param parentId the object id + */ void createChildren(String parentId); + /** + * Destroys the children of a specified object. + * + * @param parentId the object id + */ void destroyChildren(String parentId); + /** + * Create a relationship between a parent and one of its children. When this callback occurs the context + * should already be populated with the specified parent object and child object. + * + * @param parentId the parent id + * @param childId the child id + */ void addChild(String parentId, String childId); + /** + * Destroys a relationship between a parent and one of its children. When this callback occurs the context + * should be populated with the specified parent object and child object. + * + * @param parentId the parent id + * @param childId the child id + */ void removeChild(String parentId, String childId); } Modified: branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortScope.java =================================================================== --- branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortScope.java 2008-03-28 20:57:24 UTC (rev 10409) +++ branches/presentation/presentation/src/main/org/jboss/portal/presentation/model2/ViewPortScope.java 2008-03-28 21:23:51 UTC (rev 10410) @@ -23,6 +23,10 @@ package org.jboss.portal.presentation.model2; /** + * Defines the scope of a viewport. This interface is separated from the viewport context in order to + * really affirm the split between the concern between the scope implementation that is used by the viewport + * to populate the viewport context during a refresh operation. + * * @author <a href="mailto:julien@jboss-portal.org">Julien Viet</a> * @version $Revision: 630 $ */ @@ -44,7 +48,8 @@ ObjectTraversalType enterObject(UIObject object); /** - * Callback to signal that an object visit is terminated + * Callback to signal that an object visit is terminated. It can be used by the scope to maintain a data + * structure of the traversed model. * * @param object the object */