You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by ma...@apache.org on 2008/01/17 20:23:47 UTC
svn commit: r612942 - in
/myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component:
ComponentProcessingContext.java ComponentProcessor.java
FlattenedComponent.java
Author: matzew
Date: Thu Jan 17 11:23:45 2008
New Revision: 612942
URL: http://svn.apache.org/viewvc?rev=612942&view=rev
Log:
TRINIDAD-905
Added:
myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessingContext.java
myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessor.java
myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/FlattenedComponent.java
Added: myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessingContext.java
URL: http://svn.apache.org/viewvc/myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessingContext.java?rev=612942&view=auto
==============================================================================
--- myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessingContext.java (added)
+++ myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessingContext.java Thu Jan 17 11:23:45 2008
@@ -0,0 +1,108 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.trinidad.component;
+
+import javax.faces.component.UIComponent;
+import javax.faces.context.FacesContext;
+
+/**
+ * ProcessingContext passed to FlattenedComponents and ComponentProcessors representing the
+ * current component iteration context.
+ * @see ComponentProcessor
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessor, Iterable, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
+ * @see FlattenedComponent
+ */
+public final class ComponentProcessingContext
+{
+ ComponentProcessingContext()
+ {
+ }
+
+ /**
+ * Returns the current starting group depth of the ProcessingContext. The starting depth is only
+ * non-zero for the first rendered child inside a group or nested groups. If two grouping
+ * components, such as UIXGroup, are nested immediately inside of each other, the first processed
+ * component in the second UIXGroup will see 2 for the start depth. The second would see 0.
+ * @see #getGroupDepth
+ */
+ public int getStartDepth()
+ {
+ return _startDepth;
+ }
+
+ /**
+ * Returns the current group depth of the ProcessingContext. The group depth is equal to the
+ * nesting depth of grouping components, such as UIXGroup that the current iteratior has
+ * entered. In contrast to <code>getStartDepth()</code>, all siblings at a particular nesting
+ * level see the same group depth.
+ * @see #getStartDepth
+ */
+ public int getGroupDepth()
+ {
+ return _groupDepth;
+ }
+
+ /**
+ * Increment the grouping and startGroup states.
+ * <p>
+ * If pushGroup is called, the seubsequent code should be
+ * wrapped in a <code>try{}finally{ComponentProcessingContext.popGroup()} block to guarantee
+ * that the group is popped correctly in case an exception is thrown.
+ * @see #popGroup
+ */
+ void pushGroup()
+ {
+ _startDepth++;
+ _groupDepth++;
+ }
+
+ /**
+ * Decrement the grouping and startGroup states.
+ * <p>
+ * If pushGroup is called, the seubsequent code should be
+ * wrapped in a <code>try{}finally{ComponentProcessingContext.popGroup()} block to guarantee
+ * that the group is popped correctly in case an exception is thrown.
+ * @see #pushGroup
+ */
+ void popGroup()
+ {
+ _groupDepth--;
+
+ if (_startDepth > 0)
+ _startDepth--;
+ }
+
+ /**
+ * Called by the object performing the iteration over Component instances to
+ * reset the start depth after the ChildProcessor is called on the first component at the
+ * new depth. When iterating, the iterator should place the call to <code>resetStartDepth</code>
+ * in a <code>finally</code> block to guarantee that the reset happens correctly in case
+ * an exception is thrown.
+ */
+ void resetStartDepth()
+ {
+ _startDepth = 0;
+ }
+
+ private int _startDepth;
+ private int _groupDepth;
+}
Added: myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessor.java
URL: http://svn.apache.org/viewvc/myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessor.java?rev=612942&view=auto
==============================================================================
--- myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessor.java (added)
+++ myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/ComponentProcessor.java Thu Jan 17 11:23:45 2008
@@ -0,0 +1,63 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.trinidad.component;
+
+import java.io.IOException;
+
+import javax.faces.component.UIComponent;
+import javax.faces.context.FacesContext;
+
+/**
+ * Interface implemented to apply the visitor pattern to a set of components where the
+ * components are not necessarily siblings of each other. When <code>processComponent</code> is
+ * called, the component instance is guaranteed to be in the correct context.
+ * <p>
+ * Instances of this interface are parameterized by the type of the callbackContext the implementor
+ * expects. The typical usage is that the implementor creates and instance of the desired context
+ * and calls a helper method on a different object (for example
+ * <code>UIXComponet.processComponent</code> with the desired ComponentProcessor and context
+ * instances to actually perform the iteration.
+ * <p>
+ * Because the ComponentProcessor can't look ahead, more complex iteration tasks, such as
+ * laying out and rendering components based on the number of components to render may
+ * require multiple-passes--one to collect the layout information into the callbackContext using
+ * one ComponentProcessor implementation and a second pass using a different ComponentProcessor
+ * to actually perform the layout using the information calculated in the first pass.
+ * @see FlattenedComponent
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessor, Iterable, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
+ */
+public interface ComponentProcessor<T>
+{
+ /**
+ * Processes a component
+ * @param context The current FacesContext
+ * @param cpContext context represtinging the current component iteration state
+ * @param component Component to process on this iteration
+ * @param callbackContext ComponentProcessor-specific context
+ * @throws IOException if processing resulted in an IOException
+ */
+ public void processComponent(
+ FacesContext context,
+ ComponentProcessingContext cpContext,
+ UIComponent component,
+ T callbackContext) throws IOException;
+}
Added: myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/FlattenedComponent.java
URL: http://svn.apache.org/viewvc/myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/FlattenedComponent.java?rev=612942&view=auto
==============================================================================
--- myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/FlattenedComponent.java (added)
+++ myfaces/trinidad/branches/1.2.5.1-branch/trinidad-api/src/main/java/org/apache/myfaces/trinidad/component/FlattenedComponent.java Thu Jan 17 11:23:45 2008
@@ -0,0 +1,94 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.myfaces.trinidad.component;
+
+import java.io.IOException;
+
+import javax.faces.context.FacesContext;
+
+/**
+ * Interface implemented by Components that don't render any content themselves but rather set
+ * up context before asking their children to render themselves. Implementing this interface
+ * enables Renderers for components that contain instances of the FlattenedComponents to
+ * visit each descendant in a flattened view of their children, recursively including any
+ * FlattenedComponent treating all of these descendants as direct children.
+ * <p>
+ * A good indicator that a
+ * component should implement FlattenedComponent is that the component doesn't delegate to a
+ * Renderer, but rather renders itself.
+ *
+ * @see ComponentProcessor
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
+ */
+public interface FlattenedComponent
+{
+ /**
+ * Set up the component context, process all of the renderable children of this component,
+ * and the restore the previous context, returning <code>true</code> if any of the children
+ * were processed.
+ * <p>
+ * The context set up and tear down to perform is identical to that which the component
+ * would perform when handling rendering or implementing <code>invokeOnComponent</code>
+ * <p>
+ * To handle actually processing the children, the component will typically delegate to one
+ * of the two <code>UIXComponent.processFlattenedChildren</code> helpers. If the component only
+ * processes a single child, as UIXSwitcher does, it will call the version taking a single child
+ * as the argument. If it processes all of its children as UIXIterator and UIXGroup do, it
+ * will call <code>getChildren</code> and pass the List<UIComponent> to the version accepting
+ * an Iterable<UIComponent>.
+ * <p>
+ * This method should only be called if <code>FlattenedComponent.isFlatteningChildren</code>
+ * returns <code>true</code>. If called when <code>FlattenedComponent.isFlatteningChildren</code>
+ * is <code>false</code> the behavior is undefined and the implementation may throw an
+ * IllegalStateException.
+ * <p>
+ * This method may only be called when the FlattenedComponent is in the correct context
+ * to process itself.
+ * @param context Current FacesContext
+ * @param cpContext ComponentProcesingContext represetning the current child iteration state
+ * @param childProcessor ComponentProcessor to call for each flattened child
+ * @param callbackContext childProcessor-specific context to be passed on each call to the
+ * childProcessor
+ * @return <code>true</code> if this FlattenedComponent actually processed any children
+ * @throws IOException if an error occurs while processing children
+ * @throws IllegalStateException if called when <code>isFlatteningChildren()</code> is
+ * <code>false</code>.
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, UIComponent, Object)
+ * @see UIXComponent#processFlattenedChildren(FacesContext, ComponentProcessingContext, ComponentProcessor, Iterable, Object)
+ * @see #isFlatteningChildren
+ */
+ public <S> boolean processFlattenedChildren(
+ FacesContext context,
+ ComponentProcessingContext cpContext,
+ ComponentProcessor<S> childProcessor,
+ S callbackContext) throws IOException;
+
+ /**
+ * Returns <code>true</code> if this FlattenedComponent is currently flattening its children. This
+ * allows a FlattenedComponent instance to flatten or not flatten its children as it sees fit.
+ * <p>
+ * It is illegal to call <code>processFlattenedChildren</code> on a FlattenedComponent that
+ * has returned <code>false</code> from <code>isFlatteningChildren</code>.
+ * @param context FacesContext
+ * @return <code>true</code> if this FlattenedComponent is currently flattening its children
+ * @see #processFlattenedChildren
+ */
+ public boolean isFlatteningChildren(FacesContext context);
+}