View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.renderkit.html.util;
20  
21  import javax.faces.context.FacesContext;
22  
23  /**
24   * Represents a single resource that a component in a page needs a
25   * browser to fetch. This class helps generate the URI that is emitted
26   * into the page, and specifies the class that should be invoked to
27   * handle the request for that URI when the browser makes it.
28   *
29   * @author Mathias Broekelmann
30   */
31  public interface ResourceHandler
32  {
33      /**
34       * Return a Class object whose instance can decode the url generated
35       * by this class in the getResourceUri method and use that info to
36       * locate the resource data represented by this object. When a
37       * browser requests the data in the URL generated by this class
38       * and its callers, an instance of the returned class shall be
39       * created to decode the remainder of the url and serve the
40       * resource.
41       * 
42       * @return a class which implements
43       *   org.apache.myfaces.component.html.util.ResourceLoader
44       *
45       * @see ResourceLoader
46       */
47      public Class getResourceLoaderClass(); 
48      
49      /**
50       * Returns the uri part which is used by the resourceloader to
51       * identify the resource to load. This URI will be interpreted
52       * by an instance of the class returned by getResourceLoaderClass. 
53       * 
54       * @see org.apache.myfaces.renderkit.html.util.ResourceLoader#serveResource(javax.servlet.ServletContext, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, String)
55       */
56      public String getResourceUri(FacesContext context);
57      
58      /**
59       * Must always be implemented when equals is overridden.
60       * 
61       * @see java.lang.Object#hashCode()
62       */
63      public int hashCode();
64      
65      /**
66       * Must be implemented to avoid loading the same resource multiple times.
67       * <p>
68       * When the same component is used multiple times in a page and that
69       * component needs an external resource such as a script, multiple calls
70       * will be made to the AddResource methods for the same resource. The
71       * AddResource class will create an instance of this class for each such
72       * call. However if there is already a ResourceHandler instance existing
73       * which is "equal" to the newly created one then a duplicate will not
74       * be queued for output. 
75       * 
76       * @see java.lang.Object#equals(java.lang.Object)
77       */
78      public boolean equals(Object obj);
79  }