2009/05/20 - Apache Shale has been retired.

For more information, please explore the Attic.


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to you under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.shale.remoting;
19  
20  import java.util.List;
21  
22  /***
23   * <p>Configuration object used to manage the {@link Mapping} instances for
24   * a particular web application.</p>
25   */
26  public interface Mappings {
27  
28  
29      /***
30       * <p>Add the specified {@link Mapping} to the set of mappings for which
31       * remoting services are supplied.</p>
32       *
33       * @param mapping The new {@link Mapping} to be added
34       *
35       * @exception IllegalStateException if there is an existing {@link Mapping}
36       *  already defined for the specified <code>pattern</code>
37       * @exception NullPointerException if <code>mapping</code> is <code>null</code>
38       */
39      public void addMapping(Mapping mapping);
40  
41  
42      /***
43       * <p>Return the extension that will replace the <code>FacesServlet</code>
44       * extension pattern, if <code>FacesServlet</code> is extension mapped.</p>
45       */
46      public String getExtension();
47  
48  
49      /***
50       * <p>Return the {@link Mapping}, if any, for the specified matching
51       * <code>pattern</code>.  If there is no such {@link Mapping}, return
52       * <code>null</code> instead.</p>
53       *
54       * @param pattern Matching pattern for which to return a {@link Mapping}
55       */
56      public Mapping getMapping(String pattern);
57  
58  
59      /***
60       * <p>Return a <code>List</code> of all the currently defined {@link Mapping}s
61       * for this application.  If there are no currently defined {@link Mapping}s,
62       * an empty <code>List</code> is returned.</p>
63       */
64      public List getMappings();
65  
66  
67      /***
68       * <p>Return the zero-relative index, into the array returned by
69       * <code>getPatterns()</code>, of the URL pattern to be used by default
70       * when creating URLs for resources.</p>
71       *
72       * @since 1.0.4
73       */
74      public int getPatternIndex();
75  
76  
77      /***
78       * <p>Set the zero-relative index, into the array returned by
79       * <code>getPatterns()</code>, of the URL pattern to be used by default
80       * when creating URLs for resources.  If not called, the default value
81       * will be zero.</p>
82       *
83       * @param patternIndex The new pattern index
84       *
85       * @since 1.0.4
86       */
87      public void setPatternIndex(int patternIndex);
88  
89  
90      /***
91       * <p>Return a list of URL patterns that this application has mapped to
92       * <code>FacesServlet</code>.  This information is useful to renderers that
93       * wish to dynamically calculate URLs that will be guaranteed to trigger
94       * the JSF request processing lifecycle.</p>
95       */
96      public String[] getPatterns();
97  
98  
99      /***
100      * <p>Remove the specified {@link Mapping} from the set of mappings for which
101      * remoting services are supplied, if it is currently included.</p>
102      *
103      * @param mapping The {@link Mapping} to be removed
104      *
105      * @exception NullPointerException if <code>mapping</code> is <code>null</code>
106      */
107     public void removeMapping(Mapping mapping);
108 
109 
110     /***
111      * <p>Set the extension that will replace the <code>FacesServlet</code>
112      * extension pattern, if <code>FacesServlet</code> is extension mapped.</p>
113      *
114      * @param extension The new extension
115      */
116     public void setExtension(String extension);
117 
118 
119     /***
120      * <p>Set a list of URL patterns that this application has mapped to
121      * <code>FacesServlet</code>.  If no patterns are known, this SHOULD
122      * be set to a zero-length array, rather than <code>null</code>.</p>
123      *
124      * @param patterns The new list of patterns
125      */
126     public void setPatterns(String[] patterns);
127 
128 
129 }