SwitchSelector


1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.selection;
17  
18  import org.apache.avalon.framework.parameters.Parameters;
19  import org.apache.avalon.framework.thread.ThreadSafe;
20  
21  import java.util.Map  ;
22  
23  /**
24   * SwitchSelector is an enhanced Selector interface that allows a
25   * context object to be created to optimize selector conditional testing.
26   *
27   * <p>
28   * The original Selector interface supports an <code>if-then-else</code> style
29   * of conditional testing depending on whether a particular expression is true.
30   * This causes Selector.select() to be invoked for each &lt;map:when&gt;
31   * statement which may be undesirable due to performance or logic reasons.
32   * </p>
33   *
34   * <p>
35   *  <pre>
36   *  Example, the following sitemap snippet:
37   *
38   *  &lt;map:select type="aSelector"&gt;
39   *   &lt;map:when test="test-expr1"&gt;...&lt;/map:when&gt;
40   *   &lt;map:when test="test-expr2"&gt;...&lt;/map:when&gt;
41   *  &lt;/map:select&gt;
42   *
43   *  is interpreted as (pseudo-code):
44   *
45   *  if (aSelector.select("test-expr1", objectModel, params)) {
46   *   ...
47   *  } else if (aSelector.select("test-expr2", objectModel, params)) {
48   *   ...
49   *  }
50   *
51   *  ie. aSelector.select(...) is called once for each &lt;map:when&gt;
52   *  statement.
53   *  </pre>
54   * </p>
55   *
56   * <p>
57   * SwitchSelector allows the developer to first create a
58   * context object which is passed with each call to select(). This context
59   * object is created before any conditional tests are made, and hence can be
60   * used to optimize conditional testing.
61   * </p>
62   *
63   * <p>
64   *  <pre>
65   *  The above example implemented as a SwitchSelector would be
66   *  interpreted as (psuedo-code):
67   *
68   *  Object selectorContext = aSelector.getSelectorContext(objectModel, params);
69   *  
70   *  if (aSelector.select("test-expr1", selectorContext)) {
71   *   ...
72   *  else if (aSelector.select("test-expr2", selectorContext)) {
73   *   ...
74   *  }
75   *
76   *  ie. the bulk of the selector's work is done in getSelectorContext(),
77   *  select() simply compares whether the expression should be considered true. 
78   *  </pre>
79   * </p>
80   *
81   * @author <a HREF="mailto:crafterm@apache.org">Marcus Crafter</a>
82   * @author <a HREF="mailto:sylvain@apache.org">Sylvain Wallez</a>
83   * @version CVS $Id: SwitchSelector.java 30932 2004-07-29 17:35:38Z vgritsenko $
84   */
85  public interface SwitchSelector extends Selector, ThreadSafe {
86  
87      String   ROLE = SwitchSelector.class.getName();
88  
89      /**
90       * Method to create a selector context.
91       *
92       * @param objectModel The <code>Map</code> containing object of the
93       *                    calling environment which may be used
94       *                    to select values to test the expression.
95       * @param parameters  The sitemap parameters, as specified by
96       *                    &lt;parameter/&gt; tags.
97       * @return            Selector context
98       */
99      Object   getSelectorContext(Map   objectModel, Parameters parameters);
100 
101     /**
102      * Switch Selectors test patterns against a context object
103      * and signal success with the returned boolean value
104      * @param expression  The expression to test.
105      * @param selectorContext The context this test should be performed in.
106      * @return            true if the test was successful.
107      */
108     boolean select(String   expression, Object   selectorContext);
109 }
110 
111 
112
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags