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<URL> urls are calculated in this way
88 * ( see JSF 2.0 spec section 11.4.2 for definitions )
89 * </p>
90 * <ol>
91 * <li>All resources that match either "META-INF/faces-config.xml" or end with ".facesconfig.xml" directly in
92 * the "META-INF" directory (considered <code>applicationConfigurationResources)</code></li>
93 * </ol>
94 *
95 * @deprecated
96 * @return
97 */
98 @Deprecated
99 public abstract Set<URL> getBaseUrls() throws IOException;
100
101 /**
102 * Same as getBaseUrls(), but with the ExternalContext reference.
103 * By default it calls to getBaseUrls()
104 *
105 * @since 2.1.9, 2.0.15
106 * @param ctx
107 * @return
108 * @throws IOException
109 */
110 public Set<URL> getBaseUrls(ExternalContext ctx) throws IOException
111 {
112 return getBaseUrls();
113 }
114
115 public AnnotationProvider getWrapped()
116 {
117 return null;
118 }
119 }