Debian Codegraph @

spec/src/main/doc/packagingdeployment.asciidoc

raw
1 [[packaging_deployment]]
2
3 == Packaging and deployment
4
5 When an application is started, the container must perform _bean discovery_, detect definition errors and deployment problems and raise events that allow portable extensions to integrate with the deployment lifecycle.
6
7 Bean discovery is the process of determining:
8
9 * The bean archives that exist in the application, and the beans they contain
10 * Which alternatives, interceptors and decorators are _enabled_ for each bean archive
11 * The _ordering_ of enabled interceptors and decorators
12
13
14 Additional beans may be registered programmatically with the container by the application or a portable extension after the automatic bean discovery completes. Portable extensions may even integrate with the process of building the +Bean+ object for a bean, to enhance the container's built-in functionality.
15
16 [[bean_archive]]
17
18 === Bean archives
19
20 Bean classes of enabled beans must be deployed in _bean archives_.
21
22 A bean archive has a _bean discovery mode_ of +all+, +annotated+ or +none+. A bean archive which contains a +beans.xml+ file with no version has a default bean discovery mode of +all+. A bean archive which contains a +beans.xml+ file with version 1.1 (or later) must specify the +bean-discovey-mode+ attribute. The default value for the attribute is +annotated+.
23
24 An archive which:
25
26 * contains a +beans.xml+ file with the +bean-discovery-mode+ of +none+, or,
27 * contains an extension and no +beans.xml+ file
28
29 is not a bean archive.
30
31 An _explicit bean archive_ is an archive which contains a +beans.xml+ file:
32
33 * with a version number of +1.1+ (or later), with the +bean-discovery-mode+ of +all+, or,
34 * with no version number, or,
35 * that is an empty file.
36
37 An _implicit bean archive_ is any other archive which contains one or more bean classes with a bean defining annotation as defined in <<bean_defining_annotations>>, or one or more session beans.
38
39 When determining which archives are bean archives, the container must consider:
40
41 * Library jars, EJB jars or application client jars
42 * The +WEB-INF/classes+ directory of a war
43 * Directories in the JVM classpath
44
45 The container is not required to support application client jar bean archives.
46
47 A Java EE container is required by the Java EE specification to support Java EE modules. Other containers may or may not provide support for war, EJB jar or rar bean archives.
48
49 The +beans.xml+ file must be named:
50
51 * +META-INF/beans.xml+ , or,
52 * in a war, +WEB-INF/beans.xml+ or +WEB-INF/classes/META-INF/beans.xml+.
53
54 If a war has a file named +beans.xml+ in both the +WEB-INF+ directory and in the +WEB-INF/classes/META-INF+ directory, then non-portable behavior results. Portable applications must have a +beans.xml+ file in only one of the +WEB-INF+ or the +WEB-INF/classes/META-INF+ directories.
55
56 For compatibility with Contexts and Dependency 1.0, products must contain an option to cause an archive to be ignored by the container when no +beans.xml+ is present.
57
58 The container searches for beans in all bean archives in the application classpath:
59
60 * In an application deployed as an ear, the container searches every bean archive bundled with or referenced by the ear, including bean archives bundled with or referenced by wars, EJB jars and rars contained in the ear. The bean archives might be library jars, EJB jars or war +WEB-INF/classes+ directories.
61 * In an application deployed as a war, the container searches every bean archive bundled with or referenced by the war. The bean archives might be library jars or the +WEB-INF/classes+ directory.
62 * In an application deployed as an EJB jar, the container searches the EJB jar, if it is a bean archive, and every bean archive referenced by the EJB jar.
63 * In an application deployed as a rar, the container searches every bean archive bundled with or referenced by the rar.
64 * An embeddable EJB container searches each bean archive in the JVM classpath that is listed in the value of the embeddable container initialization property +javax.ejb.embeddable.modules+, or every bean archive in the JVM classpath if the property is not specified. The bean archives might be directories, library jars or EJB jars.
65
66 If a bean class is deployed in two different bean archives, non-portable behavior results. Portable applications must deploy each bean class in no more than one bean archive.
67
68 Explicit bean archives may contain classes which are not deployed as beans. For example a bean archive might contain message-driven beans.
69
70 Implicit bean archives are likely to contain classes which are not deployed as beans.
71
72 An extension may be deployed in any archive, including those that are not bean archives.
73
74 [[initialization]]
75
76 === Application initialization lifecycle
77
78 When an application is started, the container performs the following steps:
79
80 * First, the container must search for service providers for the service +javax.enterprise.inject.spi.Extension+ defined in <<init_events>>, instantiate a single instance of each service provider, and search the service provider class for observer methods of initialization events.
81 * Next, the container must fire an event of type +BeforeBeanDiscovery+, as defined in <<bbd>>.
82 * Next, the container must perform type discovery, as defined in <<type_discovery_steps>>.
83 * Next, the container must fire an event of type +AfterTypeDiscovery+, as defined in <<atd>>.
84 * Next, the container must perform bean discovery, as defined in <<bean_discovery_steps>>.
85 * Next, the container must fire an event of type +AfterBeanDiscovery+, as defined in <<abd>>, and abort initialization of the application if any observer registers a definition error.
86 * Next, the container must detect deployment problems by validating bean dependencies and specialization and abort initialization of the application if any deployment problems exist, as defined in <<exceptions>>.
87 * Next, the container must fire an event of type +AfterDeploymentValidation+, as defined in <<adv>>, and abort initialization of the application if any observer registers a deployment problem.
88 * Finally, the container begins directing requests to the application.
89
90
91 [[shutdown]]
92
93 === Application shutdown lifecycle
94
95 When an application is stopped, the container performs the following steps:
96
97 * First, the container must destroy all contexts.
98 * Finally, the container must fire an event of type +BeforeShutdown+, as defined in <<bs>>.
99
100
101 [[type_bean_discovery]]
102
103 === Type and Bean discovery
104
105 The container automatically discovers managed beans (according to the rules of <<what_classes_are_beans>>) and session beans in bean archives and searches the bean classes for producer methods, producer fields, disposer methods and observer methods.
106
107 [[type_discovery]]
108
109 ==== Type discovery
110
111 First the container must discover types. The container discovers:
112
113 * each Java class, interface (excluding the special kind of interface declaration _annotation type_) or enum deployed in an explicit bean archive, and
114 * each Java class with a bean defining annotation in an implicit bean archive.
115 * each session bean
116
117 that is not excluded from discovery by an _exclude filter_ as defined in <<exclude_filters>>.
118
119 Then, for every type discovered the container must create an +AnnotatedType+ representing the type and fire an event of type +ProcessAnnotatedType+, as defined in <<pat>>.
120
121 If an extension calls +BeforeBeanDiscovery.addAnnotatedType()+ or +AfterTypeDiscovery.addAnnotatedType()+, the type passed must be added to the set of discovered types and the container must fire an event of type +ProcessSyntheticAnnotatedType+ for every type added, as defined in <<pat>>+
122
123 [[exclude_filters]]
124
125 ==== Exclude filters
126
127 Exclude filters are defined by +<exclude>+ elements in the +beans.xml+ for the bean archive as children of the +<scan>+ element. By default an exclude filter is active. If the exclude filter definition contains:
128
129 * a child element named +<if-class-available>+ with a +name+ attribute, and the classloader for the bean archive can not load a class for that name, or
130 * a child element named +<if-class-not-available>+ with a +name+ attribute, and the classloader for the bean archive can load a class for that name, or
131 * a child element named +<if-system-property>+ with a +name+ attribute, and there is no system property defined for that name, or
132 * a child element named +<if-system-property>+ with a +name+ attribute and a +value+ attribute, and there is no system property defined for that name with that value.
133
134 then the filter is inactive.
135
136 If the filter is active, and:
137
138 * the fully qualified name of the type being discovered matches the value of the name attribute of the exclude filter, or
139 * the package name of the type being discovered matches the value of the name attribute with a suffix ".*" of the exclude filter, or
140 * the package name of the type being discovered starts with the value of the name attribute with a suffix ".**" of the exclude filter
141
142 then we say that the type is excluded from discovery.
143
144 For example, consider the follow +beans.xml+ file:
145
146 [source, xml]
147 ----
148 <?xml version="1.0" encoding="UTF-8"?>
149 <beans xmlns="http://xmlns.jcp.org/xml/ns/javaee">
150
151 <scan>
152 <exclude name="com.acme.rest.*" />
153
154 <exclude name="com.acme.faces.**">
155 <if-class-not-available name="javax.faces.context.FacesContext"/>
156 </exclude>
157
158 <exclude name="com.acme.verbose.*">
159 <if-system-property name="verbosity" value="low"/>
160 </exclude>
161
162 <exclude name="com.acme.ejb.**">
163 <if-class-available name="javax.enterprise.inject.Model"/>
164 <if-system-property name="exclude-ejbs"/>
165 </exclude>
166 </scan>
167
168 </beans>
169 ----
170
171 The first exclude filter will exclude all classes in +com.acme.rest+ package. The second exclude filter will exclude all classes in the +com.acme.faces+ package, and any subpackages, but only if JSF is not available. The third exclude filter will exclude all classes in the +com.acme.verbose+ package if the system property +verbosity+ has the value +low+. The fourth exclude filter will exclude all classes in the +com.acme.ejb+ package, and any subpackages if the system property +exclude-ejbs+ is set (with any value) and at the same time, the +javax.enterprise.inject.Model+ class is available to the classloader.
172
173
174 [[bean_discovery]]
175
176 ==== Bean discovery
177
178 For every type in the set of discovered types (as defined in <<type_discovery>>), the container must:
179
180 * inspect the type metadata to determine if it is a bean or other Java EE component class supporting injection, and then
181 * detect definition errors by validating the class and its metadata, and then
182 * if the class is a managed bean, session bean, or other Java EE component class supporting injection, fire an event of type +ProcessInjectionPoint+ for each injection point in the class, as defined in <<pip>>, and then
183 * if the class is a managed bean, session bean, or other Java EE component class supporting injection, fire an event of type +ProcessInjectionTarget+, as defined in <<pit>>, and then
184 * determine which alternatives, interceptors and decorators are enabled, according to the rules defined in <<enablement>>, <<enabled_interceptors>> and <<enabled_decorators>>, and then
185 * if the class is an enabled bean, interceptor or decorator, fire an event of type +ProcessBeanAttributes+, as defined in <<pba>>, and then
186 * if the class is an enabled bean, interceptor or decorator and if +ProcessBeanAttributes.veto()+ wasn't called in previous step, fire an event which is a subtype of +ProcessBean+, as defined in <<pb>>.
187
188 For each enabled bean, the container must search the class for producer methods and fields, as defined in <<producer_method>> and in <<producer_field>>, including resources, and for each producer:
189
190 * if it is a producer method, fire an event of type +ProcessInjectionPoint+ for each injection point in the method parameters, as defined in <<pip>>, and then
191 * fire an event of type +ProcessProducer+, as defined in <<pp>>, and then
192 * if the producer method or field is enabled, fire an event of type +ProcessBeanAttributes+, as defined in <<pba>>, and then
193 * if the producer method or field is enabled and if +ProcessBeanAttributes.veto()+ wasn't called in previous step, fire an event which is a subtype of +ProcessBean+, as defined in <<pb>>.
194
195 For each enabled bean, the container must search for disposer methods as defined in <<disposer_method>>, and for each disposer method:
196
197 * fire an event of type +ProcessInjectionPoint+ for each injection point in the method parameters, as defined in <<pip>>.
198
199 For each enabled bean, the container must search the class for observer methods, and for each observer method:
200
201 * fire an event of type +ProcessInjectionPoint+ for each injection point in the method parameters, as defined in <<pip>>, and then
202 * fire an event of type +ProcessObserverMethod+, as defined in <<pom>>.
203
204 Then, the container registers the +Bean+ and +ObserverMethod+ objects:
205
206 * For each enabled bean that is not an interceptor or decorator, the container registers an instance of the +Bean+ interface defined in <<bean>>.
207 * For each enabled interceptor, the container registers an instance of the +Interceptor+ interface defined in <<interceptor>>.
208 * For each enabled decorator, the container registers an instance of the +Decorator+ interface defined in <<decorator>>.
209 * For each observer method of every enabled bean, the container registers an instance of the +ObserverMethod+ interface defined in <<observer_method>>.
210
211 [[el]]
212
213 === Integration with Unified EL
214
215 The container must provide a Unified EL +ELResolver+ to the servlet engine and JSF implementation that resolves bean names using the rules of name resolution defined in <<name_resolution>> and resolving ambiguities according to <<ambig_names>>.
216
217 * If a name used in an EL expression does not resolve to any bean, the +ELResolver+ must return a null value.
218 * Otherwise, if a name used in an EL expression resolves to exactly one bean, the +ELResolver+ must return a contextual instance of the bean, as defined in <<contextual_instance>>.
219
220