com.sun.faces.spi.AnnotationProvider Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package com.sun.faces.spi;
import java.lang.annotation.Annotation;
import java.net.URI;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.Set;
import jakarta.servlet.ServletContext;
/**
*
* An integration point for integrators to provide custom annotation scanning.
*
*
*
* All AnnotationProvider
implementations must scan for the following annotations:
*
*
* - FacesComponent
* - FacesConverter
* - FacesRenderer
* - FacesValidator
* - ManagedBean
* - NamedEvent
* - FacesBehavior
* - FacesBehaviorRenderer
*
*
*
* The AnnotationProvider
instance will be wrapped as a {@link java.util.concurrent.Future} and executed
* during the environment initialization. The result of the future can be obtained by calling
* {@link com.sun.faces.config.ConfigManager#getAnnotatedClasses(jakarta.faces.context.FacesContext)}.
*
*
*
* The {@link java.util.concurrent.Future} itself can be obtained from the application map using the key
* com.sun.faces.config.ConfigManager__ANNOTATION_SCAN_TASK
.
*
*
*
* It's important to note that the value returned by either method described above is only available while the
* application is being initialized and will be removed before the application is put into service.
*
*
*
* To register a custom AnnotationProvider with the runtime, place a file named com.sun.faces.spi.annotationprovider
* within META-INF/services of a JAR file, with a single line referencing the fully qualified class name of the
* AnnotationProvider implementation. Custom AnnotationProviders can be used to decorate the default AnnotationProvider
* by providing a constructor that takes an AnnotationProvider as the second parameter:
*
*
*
* public AnnotationProvider(ServletContext sc, AnnotationProvider parent)
*
*
*
* If decoration is not desired, then the custom provider must have a constructor that takes one paramer, a
* ServletContext
:
*
*
* public AnnotationProvider(ServletContext sc)
*
*
*
* All customer providers must extend this class.
*
*
*/
public abstract class AnnotationProvider {
protected ServletContext servletContext;
/**
* The wrapped annotation provider. May be null if this class is not loaded via {@link ServiceLoader} (from a file named
* com.sun.faces.spi.AnnotationProvider) and is instead loaded via Mojarra's {@link ServiceFactory} (from a file named
* com.sun.faces.spi.annotationprovider).
*/
protected AnnotationProvider wrappedAnnotationProvider;
// ------------------------------------------------------------ Constructors
public AnnotationProvider(ServletContext servletContext) {
initialize(servletContext, null);
}
public AnnotationProvider() {
}
// ---------------------------------------------------------- Package Methods
final void initialize(ServletContext servletContext, AnnotationProvider wrappedAnnotationProvider) {
if (this.servletContext == null) {
this.servletContext = servletContext;
}
if (this.wrappedAnnotationProvider == null) {
this.wrappedAnnotationProvider = wrappedAnnotationProvider;
}
}
// ---------------------------------------------------------- Public Methods
/**
* @param urls a Set
of URLs that refer to specific faces-config.xml documents on the classpath. The
* information returned by the map may return annotation information from sources outside of those defined by the urls.
* @return a Map
of classes mapped to a specific annotation type. If no annotations are present, this
* method returns an empty Map
.
*/
public abstract Map, Set>> getAnnotatedClasses(Set urls);
}