Source Code Cross Referenced for SwitchSelector.java in  » Content-Management-System » apache-lenya-2.0 » org » apache » cocoon » selection » Java Source Code / Java DocumentationJava Source Code and Java Documentation

001:        /*
002:         * Licensed to the Apache Software Foundation (ASF) under one or more
003:         * contributor license agreements.  See the NOTICE file distributed with
004:         * this work for additional information regarding copyright ownership.
005:         * The ASF licenses this file to You under the Apache License, Version 2.0
006:         * (the "License"); you may not use this file except in compliance with
007:         * the License.  You may obtain a copy of the License at
008:         * 
009:         *      http://www.apache.org/licenses/LICENSE-2.0
010:         * 
011:         * Unless required by applicable law or agreed to in writing, software
012:         * distributed under the License is distributed on an "AS IS" BASIS,
013:         * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014:         * See the License for the specific language governing permissions and
015:         * limitations under the License.
016:         */
017:        package org.apache.cocoon.selection;
018:
019:        import org.apache.avalon.framework.parameters.Parameters;
020:        import org.apache.avalon.framework.thread.ThreadSafe;
021:
022:        import java.util.Map;
023:
024:        /**
025:         * SwitchSelector is an enhanced Selector interface that allows a
026:         * context object to be created to optimize selector conditional testing.
027:         *
028:         * <p>
029:         * The original Selector interface supports an <code>if-then-else</code> style
030:         * of conditional testing depending on whether a particular expression is true.
031:         * This causes Selector.select() to be invoked for each &lt;map:when&gt;
032:         * statement which may be undesirable due to performance or logic reasons.
033:         * </p>
034:         *
035:         * <p>
036:         *  <pre>
037:         *  Example, the following sitemap snippet:
038:         *
039:         *  &lt;map:select type="aSelector"&gt;
040:         *   &lt;map:when test="test-expr1"&gt;...&lt;/map:when&gt;
041:         *   &lt;map:when test="test-expr2"&gt;...&lt;/map:when&gt;
042:         *  &lt;/map:select&gt;
043:         *
044:         *  is interpreted as (pseudo-code):
045:         *
046:         *  if (aSelector.select("test-expr1", objectModel, params)) {
047:         *   ...
048:         *  } else if (aSelector.select("test-expr2", objectModel, params)) {
049:         *   ...
050:         *  }
051:         *
052:         *  ie. aSelector.select(...) is called once for each &lt;map:when&gt;
053:         *  statement.
054:         *  </pre>
055:         * </p>
056:         *
057:         * <p>
058:         * SwitchSelector allows the developer to first create a
059:         * context object which is passed with each call to select(). This context
060:         * object is created before any conditional tests are made, and hence can be
061:         * used to optimize conditional testing.
062:         * </p>
063:         *
064:         * <p>
065:         *  <pre>
066:         *  The above example implemented as a SwitchSelector would be
067:         *  interpreted as (psuedo-code):
068:         *
069:         *  Object selectorContext = aSelector.getSelectorContext(objectModel, params);
070:         *  
071:         *  if (aSelector.select("test-expr1", selectorContext)) {
072:         *   ...
073:         *  else if (aSelector.select("test-expr2", selectorContext)) {
074:         *   ...
075:         *  }
076:         *
077:         *  ie. the bulk of the selector's work is done in getSelectorContext(),
078:         *  select() simply compares whether the expression should be considered true. 
079:         *  </pre>
080:         * </p>
081:         *
082:         * @author <a href="mailto:crafterm@apache.org">Marcus Crafter</a>
083:         * @author <a href="mailto:sylvain@apache.org">Sylvain Wallez</a>
084:         * @version CVS $Id: SwitchSelector.java 433543 2006-08-22 06:22:54Z crossley $
085:         */
086:        public interface SwitchSelector extends Selector, ThreadSafe {
087:
088:            String ROLE = SwitchSelector.class.getName();
089:
090:            /**
091:             * Method to create a selector context.
092:             *
093:             * @param objectModel The <code>Map</code> containing object of the
094:             *                    calling environment which may be used
095:             *                    to select values to test the expression.
096:             * @param parameters  The sitemap parameters, as specified by
097:             *                    &lt;parameter/&gt; tags.
098:             * @return            Selector context
099:             */
100:            Object getSelectorContext(Map objectModel, Parameters parameters);
101:
102:            /**
103:             * Switch Selectors test patterns against a context object
104:             * and signal success with the returned boolean value
105:             * @param expression  The expression to test.
106:             * @param selectorContext The context this test should be performed in.
107:             * @return            true if the test was successful.
108:             */
109:            boolean select(String expression, Object selectorContext);
110:        }