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.spi;
20  
21  import java.io.IOException;
22  import java.lang.annotation.Annotation;
23  import java.net.URL;
24  import java.util.Map;
25  import java.util.Set;
26  
27  import javax.faces.FacesWrapper;
28  import javax.faces.context.ExternalContext;
29  
30  /**
31   * This interface provide a way to override myfaces annotation scanning algorithm that
32   * needs to be found at startup: 
33   * 
34   * <ul>
35   * <li>{@link javax.faces.bean.ManagedBean}</li>
36   * <li>{@link javax.faces.component.FacesComponent}</li>
37   * <li>{@link javax.faces.component.behavior.FacesBehavior}</li>
38   * <li>{@link javax.faces.convert.FacesConverter}</li>
39   * <li>{@link javax.faces.event.NamedEvent}</li>
40   * <li>{@link javax.faces.render.FacesRenderer}</li>
41   * <li>{@link javax.faces.render.FacesBehaviorRenderer}</li>
42   * <li>{@link javax.faces.validator.FacesValidator}</li>
43   * </ul>
44   * 
45   * <p>This is provided to allow application containers solve the following points</p>
46   * <ul>
47   * <li>It is common application containers to have its own protocols to handle files. It is
48   * not the same to scan annotation inside a jar than look on a directory.</li>
49   * <li>If the application container has some optimization related to annotation scanning or
50   * it already did that task, it is better to reuse that information instead do the same
51   * thing twice.</li>
52   * </ul>
53   * 
54   * <p>To override this class, create a file on a jar file with the following entry name:
55   * /META-INF/services/org.apache.myfaces.spi.AnnotationProvider and put the desired class name of
56   * the class that will override or extend the default AnnotationProvider.
57   * </p>
58   * 
59   * <p>To wrap the default AnnotationProvider, use a constructor like 
60   * CustomAnnotationProvider(AnnotationProvider ap)</p>
61   * 
62   * @since 2.0.2
63   * @author Leonardo Uribe 
64   */
65  public abstract class AnnotationProvider implements FacesWrapper<AnnotationProvider>
66  {
67  
68      /**
69       * Retrieve a map containing the classes that contains annotations used by jsf implementation at
70       * startup.
71       * <p>The default implementation must comply with JSF 2.0 spec section 11.5.1 Requirements for scanning of 
72       * classes for annotations. 
73       * </p>
74       * <p>This method could call getBaseUrls() to obtain a list of URL that could be used to indicate jar files of
75       * annotations in the classpath.
76       * </p>
77       * <p>If the <faces-config> element in the WEB-INF/faces-config.xml file contains metadata-complete attribute 
78       * whose value is "true", this method should not be called.
79       * </p>
80       * 
81       * @param ctx The current ExternalContext
82       * @return A map with all classes that could contain annotations.
83       */
84      public abstract Map<Class<? extends Annotation>,Set<Class<?>>> getAnnotatedClasses(ExternalContext ctx);
85  
86      /**
87       * <p>The returned Set&lt;URL&gt; urls are calculated in this way ( see JSF 2.0 spec section 11.4.2 for definitions )    
88       * </p>
89       * <ol>
90       * <li>All resources that match either "META-INF/faces-config.xml" or end with ".facesconfig.xml" directly in 
91       * the "META-INF" directory (considered <code>applicationConfigurationResources)<code></li>
92       * </ol>
93       * 
94       * @deprecated 
95       * @return
96       */
97      @Deprecated
98      public abstract Set<URL> getBaseUrls() throws IOException;
99      
100     /**
101      * Same as getBaseUrls(), but with the ExternalContext reference.
102      * By default it calls to getBaseUrls()
103      * 
104      * @since 2.1.9, 2.0.15
105      * @param ctx
106      * @return
107      * @throws IOException 
108      */
109     public Set<URL> getBaseUrls(ExternalContext ctx) throws IOException
110     {
111         return getBaseUrls();
112     }
113     
114     public AnnotationProvider getWrapped()
115     {
116         return null;
117     }    
118 }