WebResourcePermission


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package javax.security.jacc;
25  
26  import java.io.IOException  ;
27  import java.io.ObjectStreamField  ;
28  
29  import javax.security.jacc.URLPatternSpec  ;
30  import javax.security.jacc.HttpMethodSpec  ;
31  
32  import java.security.*;
33  
34  import javax.servlet.http.HttpServletRequest  ;
35  
36  /**
37   * Class for Servlet web resource permissions.
38   * A WebResourcePermission is a named permission and has actions.
39   * <P>
40   * The name of a WebResourcePermission (also referred to as the target name)
41   * identifies the Web resources to which the permission pertains.
42   * <P>
43   * Implementations of this class MAY implement newPermissionCollection or
44   * inherit its implementation from the super class.
45   * 
46   * @see java.security.Permission
47   *
48   * @version %I% %E%
49   *
50   * @author Ron Monzillo
51   * @author Gary Ellison
52   *
53   */
54  
55  public final class WebResourcePermission extends Permission
56  implements java.io.Serializable  
57  {
58  
59       private transient HttpMethodSpec   methodSpec;
60  
61       private transient URLPatternSpec   urlPatternSpec = null;
62  
63       private transient int hashCodeValue = 0;
64  
65       private transient static final String   EMPTY_STRING = "";
66  
67       private static final long serialVersionUID = 1L;
68  
69      /**
70       * The serialized fields of this permission are defined below. Whether
71       * or not the serialized fields correspond to actual (private) fields 
72       * is an implementation decision.
73       * @serialField actions String
74       * the canonicalized actions string (as returned by getActions).
75       */
76       private static final ObjectStreamField  [] serialPersistentFields = { 
77       new ObjectStreamField  ("actions", java.lang.String  .class)
78       };
79  
80      /**
81       * Creates a new WebResourcePermission with the specified name and actions.
82       * <P>
83       * The name contains a URLPatternSpec that identifies the web
84       * resources to which the permissions applies. The syntax of a URLPatternSpec
85       * is as follows:
86       * <P><Pre>
87       *
88       *          URLPatternList ::= URLPattern | URLPatternList colon URLPattern
89       *
90       *          URLPatternSpec ::= null | URLPattern | URLPattern colon URLPatternList
91       *
92       * </Pre><P>
93       * A null URLPatternSpec is translated to the default URLPattern, "/", by
94       * the permission constructor. The empty string is an exact URLPattern, and
95       * may occur anywhere in a URLPatternSpec that an exact URLPattern may occur.
96       * The first URLPattern in a URLPatternSpec may be any of the pattern 
97       * types, exact, path-prefix, extension, or default as defined in the
98       * <i>Java Servlet Specification)</i>. When a URLPatternSpec includes
99       * a URLPatternList, the patterns of the URLPatternList identify the
100      * resources to which the permission does NOT apply and depend on the
101      * pattern type and value of the first pattern as follows:  <p>
102      * <ul>
103      * <li> No pattern may exist in the URLPatternList that matches the
104      *      first pattern.
105      * <li> If the first pattern is a path-prefix
106      *      pattern, only exact patterns matched by the first pattern
107      *      and path-prefix patterns matched by, but different from,
108      *      the first pattern may occur in the URLPatternList.
109      * <li> If the first pattern is an extension
110      *      pattern, only exact patterns that are matched by the first 
111      *      pattern and path-prefix patterns may occur in the URLPatternList.
112      * <li> If the first pattern is the default pattern, "/", any pattern
113      *      except the default pattern may occur in the URLPatternList.
114      * <li> If the first pattern is an exact pattern a URLPatternList must not
115      *      be present in the URLPatternSpec.
116      * </ul>
117      * <P>
118      * The actions parameter contains a comma seperated list of HTTP methods.
119      * The syntax of the actions parameter is defined as follows:
120      * <P><Pre>
121      *
122      *          ExtensionMethod ::= any token as defined by RFC 2616
123      *                    (that is, 1*[any CHAR except CTLs or separators])
124      *
125      *          HTTPMethod ::= "GET" | "POST" | "PUT" | "DELETE" | "HEAD" |
126      *                   "OPTIONS" | "TRACE" | ExtensionMethod
127      *          
128      *          HTTPMethodList ::= HTTPMethod | HTTPMethodList comma HTTPMethod
129      *  
130      *          HTTPMethodExceptionList ::= exclaimationPoint HTTPMethodList
131      * 
132      *          HTTPMethodSpec ::= null | HTTPMethodExceptionList | 
133      *                   HTTPMethodList
134      *
135      * </Pre><P>
136      * If duplicates occur in the HTTPMethodSpec 
137      * they must be eliminated by the permission constructor.
138      * <P>
139      * A null or empty string HTTPMethodSpec indicates that the permission
140      * applies to all HTTP methods at the resources identified by the URL
141      * pattern.
142      * <P>
143      * If the HTTPMethodSpec contains an HTTPMethodExceptionList (i.e., 
144      * it begins with an exclaimationPoint), the permission pertains to all 
145      * methods except those occuring in the exception list.
146      * <P>
147      * @param name the URLPatternSpec that identifies the application 
148      * specific web resources to which the permission pertains. 
149      * All URLPatterns in the URLPatternSpec are relative to the context path
150      * of the deployed web application module, and the same URLPattern must not
151      * occur more than once in a URLPatternSpec. A null URLPatternSpec is 
152      * translated to the default URLPattern, "/", by the permission constructor.
153      * <P>
154      * @param actions identifies the HTTP methods to which the permission
155      * pertains. If the value passed through this parameter is null or
156      * the empty string, then the permission pertains to all the possible 
157      * HTTP methods.
158      */
159 
160      public WebResourcePermission(String   name, String   actions)
161      {  
162     super(name);
163     this.urlPatternSpec = new URLPatternSpec  (name);
164     this.methodSpec = HttpMethodSpec.getSpec(actions);
165      }
166 
167     /**
168      * Creates a new WebResourcePermission with name corresponding
169      * to the URLPatternSpec, and actions composed from the array of HTTP
170      * methods.
171      * <P>
172      * @param urlPatternSpec the URLPatternSpec that identifies the 
173      * application specific web resources to which the permission pertains.
174      * All URLPatterns in the URLPatternSpec are relative to the context path
175      * of the deployed web application module, and the same URLPattern must not
176      * occur more than once in a URLPatternSpec. A null URLPatternSpec is 
177      * translated to the default URLPattern, "/", by the permission constructor.
178      * <P>
179      * @param HTTPMethods an array of strings each element of which contains
180      * the value of an HTTP method. If the value passed through this
181      * parameter is null or is an array with no elements, then the permission
182      * pertains to all the possible HTTP methods.
183      */
184 
185      public WebResourcePermission(String   urlPatternSpec, String  [] HTTPMethods)
186      {
187     super(urlPatternSpec);
188     this.urlPatternSpec = new URLPatternSpec  (urlPatternSpec);
189     this.methodSpec = HttpMethodSpec.getSpec(HTTPMethods);
190      }
191 
192     /**
193      * Creates a new WebResourcePermission from the HttpServletRequest
194      * object.
195      * <P>
196      * @param request the HttpServletRequest object corresponding
197      * to the Servlet operation to which the permission pertains.
198      * The permission name is the substring of the requestURI 
199      * (HttpServletRequest.getRequestURI()) that begins after the contextPath
200      * (HttpServletRequest.getContextPath()). When the substring operation
201      * yields the string "/", the permission is constructed with the empty
202      * string as its name. The permission's actions field is obtained from 
203      * HttpServletRequest.getMethod().
204      */
205 
206      public WebResourcePermission(HttpServletRequest   request)
207      {
208     super(getUriMinusContextPath(request));
209     this.urlPatternSpec = new URLPatternSpec  (super.getName());
210     this.methodSpec= HttpMethodSpec.getSpec(request.getMethod());
211      }
212 
213     /**
214      * Checks two WebResourcePermission objects for equality.
215      * WebResourcePermission objects are equivalent if their 
216      * URLPatternSpec and (canonicalized) actions values are equivalent.
217      * The URLPatternSpec of a reference permission is equivalent to that
218      * of an argument permission if their first patterns are
219      * equivalent, and the patterns of the URLPatternList of the reference
220      * permission collectively match exactly the same set of patterns
221      * as are matched by the patterns of the URLPatternList of the 
222      * argument permission.
223      * <P>
224      * Two Permission objects, P1 and P2, are equivalent if and only if
225      * P1.implies(P2) && P2.implies(P1).
226      * <P>
227      * @param o the WebResourcePermission object being tested for equality
228      * with this WebResourcePermission.
229      * <P>
230      * @return true if the argument WebResourcePermission object is equivalent
231      * to this WebResourcePermission.
232      */
233 
234     public boolean equals(Object   o) {
235     if (o == null || ! (o instanceof WebResourcePermission  )) return false;
236 
237     WebResourcePermission   that = (WebResourcePermission  ) o;
238 
239     if (!this.methodSpec.equals(that.methodSpec)) return false;
240     
241     return this.urlPatternSpec.equals(that.urlPatternSpec);
242     }
243 
244    /**
245     * Returns a canonical String representation of the actions of this
246     * WebResourcePermission. In the canonical form, predefined methods
247     * preceed extension methods, and within each method classification the
248     * corresponding methods occur in ascending lexical order. There may be 
249     * no duplicate HTTP methods in the canonical form, and the canonical 
250     * form of the set of all HTTP methods is the value null.
251     * <P>
252     * @return a String containing the canonicalized actions of this
253     * WebResourcePermission (or the null value).
254     */
255 
256     public String   getActions() {
257     return this.methodSpec.getActions();
258     }
259 
260    /**
261     * Returns the hash code value for this WebResourcePermission. The
262     * properties of the returned hash code must be as follows: <p>
263     * <ul>
264     * <li> During the lifetime of a Java application, the hashCode method
265     *      must return the same integer value, every time it is called on a
266     *      WebResourcePermission object. The value returned by hashCode for a
267     *      particular WebResourcePermission need not remain consistent from
268     *      one execution of an application to another.
269     * <li> If two WebResourcePermission objects are equal according to the
270     *      equals method, then calling the hashCode method on each of the two
271     *      Permission objects must produce the same integer result (within an
272     *      application).
273     * </ul>
274     * <P>
275     * @return the integer hash code value for this object.
276     */
277 
278     public int hashCode() {
279     if (this.hashCodeValue == 0) {
280         String   hashInput = new String  (this.urlPatternSpec.toString()+ " " +
281                       this.methodSpec.hashCode());
282 
283         this.hashCodeValue = hashInput.hashCode();
284     }
285     return this.hashCodeValue;
286     }
287 
288     /**
289      * Determines if the argument Permission is "implied by" this
290      * WebResourcePermission. For this to be the case, all of the following
291      * must be true:
292      * <p><ul>
293      * <li> The argument is an instanceof WebResourcePermission
294      * <li> The first URLPattern in the name of the argument permission
295      *      is matched by the first URLPattern in the name of this permission.
296      * <li> The first URLPattern in the name of the argument permission
297      *      is NOT matched by any URLPattern in the URLPatternList of the
298      *      URLPatternSpec of this permission.
299      * <li> If the first URLPattern in the name of the argument permission
300      *      matches the first URLPattern in the URLPatternSpec of this 
301      *      permission, then every URLPattern in the URLPatternList of the
302      *      URLPatternSpec of this permission is matched by a URLPattern
303      *      in the URLPatternList of the argument permission.
304      * <li> The HTTP methods represented by the actions of the argument 
305      *      permission are a subset of the HTTP methods represented by the
306      *      actions of this permission.
307      * </ul>
308      * <P>
309      * URLPattern matching is performed using the <i>Servlet matching 
310      * rules</i> where two URL patterns match if they are related as follows:
311      * <p><ul>
312      * <li> their pattern values are String equivalent, or
313      * <li> this pattern is the path-prefix pattern "/*", or
314      * <li> this pattern is a path-prefix pattern (that is, it starts with 
315      *      "/" and ends with "/*") and the argument pattern starts with the 
316      *      substring of this pattern, minus its last 2 characters, and the
317      *      next character of the argument pattern, if there is one, is "/", or
318      * <li> this pattern is an extension pattern (that is, it starts with 
319      *      "*.") and the argument pattern ends with this pattern, or
320      * <li> the reference pattern is the special default pattern, "/",
321      *      which matches all argument patterns.
322      * </ul>
323      * <P>
324      * All of the comparisons described above are case sensitive.
325      * <P>
326      * @param permission "this" WebResourcePermission is checked to see if
327      * it implies the argument permission.
328      * <P>
329      * @return true if the specified permission is implied by this object,
330      * false if not.
331      */
332     public boolean implies(Permission permission) {
333     if (permission == null ||
334         ! (permission instanceof WebResourcePermission  )) return false;
335 
336     WebResourcePermission   that = (WebResourcePermission  ) permission;
337         
338     if (!this.methodSpec.implies(that.methodSpec)) 
339         return false;
340 
341     return this.urlPatternSpec.implies(that.urlPatternSpec);
342     }
343 
344     // ----------------- Private Methods ---------------------
345 
346     /**
347      * Chops the ContextPath off the front of the requestURI to
348      * yield the servletPath + PathInfo. For the special case where
349      * the servletPath + PathInfo is the pattern, "/", this
350      * routine returns the empty string.
351      */
352      private static String   getUriMinusContextPath(HttpServletRequest   request) {
353      String   uri = request.getRequestURI();
354      if (uri != null) {
355          String   contextPath = request.getContextPath();
356          int contextLength = contextPath == null ? 0 : contextPath.length();
357          if (contextLength > 0) {
358          uri = uri.substring(contextLength);
359          }
360          if (uri.equals("/")) {
361          uri = EMPTY_STRING;
362          }
363      } else {
364          uri = EMPTY_STRING;
365      }
366      return uri;
367      }
368 
369     /**
370      * readObject reads the serialized fields from the
371      * input stream and uses them to restore the permission. 
372      * This method need not be implemented if establishing the 
373      * values of the serialized fields (as is done by defaultReadObject) 
374      * is sufficient to initialize the permission.
375      */
376     private synchronized void readObject(java.io.ObjectInputStream   s)
377          throws IOException  ,ClassNotFoundException  
378     {
379     this.methodSpec = HttpMethodSpec.getSpec
380         ((String  ) s.readFields().get("actions",null));
381     this.urlPatternSpec = new URLPatternSpec  (super.getName());
382     }
383 
384     /**
385      * writeObject is used to establish the values of the serialized fields
386      * before they are written to the output stream and need not be
387      * implemented if the values of the serialized fields are always 
388      * available and up to date. The serialized fields are written to
389      * the output stream in the same form as they would be written
390      * by defaultWriteObject.
391      */
392     private synchronized void writeObject(java.io.ObjectOutputStream   s)
393          throws IOException  
394     {
395     s.putFields().put("actions",this.getActions());
396     s.writeFields();
397     }
398 
399 }
400 
401 
402 
403
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags