1 /**
2 *
3 * Copyright 2003-2004 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18
19
20
21
22
23
24 package javax.enterprise.deploy.spi;
25
26 import javax.enterprise.deploy.model.DDBean;
27 import javax.enterprise.deploy.model.XpathEvent;
28 import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
29 import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;
30 import java.beans.PropertyChangeListener;
31
32 /**
33 * The interface for configuring a server-specific deployment descriptor, or subset of same.
34 * A DConfigBean corresponds to a specific location in a standard deployment descriptor,
35 * typically where values (such as names and roles) are used.
36 *
37 * <p>There are three different ways that DConfigBeans are created:</p>
38 *
39 * <ul>
40 * <li><code>DeploymentConfigurator.getDConfigBean(DDBeanRoot)</code> is called by the
41 * deployment tool to create a DConfigBeanRoot for each deployment descriptor in
42 * the J2EE application.</li>
43 * <li><code>DConfigBean.getDConfigBean(DDBean)</code> is called by the deployment
44 * tool for each DDBean that corresponds to a relative XPath pattern given to the
45 * deployment tool by the method <code>DConfigBean.getXpaths()</code>.</li>
46 * <li>Each DConfigBean can structure its configurations as a tree-structure of
47 * DConfigBeans; a DConfigBean can have properties of type DConfigBean or
48 * DConfigBean[].</li>
49 * <ul>
50 *
51 * <p>The properties of DConfigBeans are displayed and edited by the deployment tool by
52 * using the JavaBean Property classes.</p>
53 *
54 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
55 */
56 public interface DConfigBean {
57 /**
58 * Return the JavaBean containing the deployment descriptor XML text associated with this DConfigBean.
59 *
60 * @return The bean class containing the XML text for this DConfigBean.
61 */
62 public DDBean getDDBean();
63
64 /**
65 * Return a list of XPaths designating the deployment descriptor information this
66 * DConfigBean requires. Each server vendor may need to specify different
67 * server-specific information. Each String returned by this method is an XPath
68 * describing a certain portion of the standard deployment descriptor for which
69 * there is corresponding server-specific configuration.
70 *
71 * @return a list of XPath Strings representing XML data to be retrieved or
72 * <code>null</code> if there are none.
73 */
74 public String[] getXpaths();
75
76 /**
77 * Return the JavaBean containing the server-specific deployment configuration
78 * information based upon the XML data provided by the DDBean.
79 *
80 * @param bean The DDBean containing the XML data to be evaluated.
81 *
82 * @return The DConfigBean to display the server-specific properties for the standard bean.
83 *
84 * @throws ConfigurationException reports errors in generating a configuration bean.
85 * This DDBean is considered undeployable to this server until this exception is
86 * resolved. A suitably descriptive message is required so the user can diagnose
87 * the error.
88 */
89 public DConfigBean getDConfigBean(DDBean bean) throws ConfigurationException;
90
91 /**
92 * Remove a child DConfigBean from this bean.
93 *
94 * @param bean The child DConfigBean to be removed.
95 *
96 * @throws BeanNotFoundException the bean provided is not in the child list of this bean.
97 */
98 public void removeDConfigBean(DConfigBean bean) throws BeanNotFoundException;
99
100 /**
101 * A notification that the DDBean provided in the event has changed and this bean
102 * or its child beans need to reevaluate themselves.
103 *
104 * <p><i>It is advisable, though not declared explicitly in the specification, for a
105 * DConfigBean to receive change events for itself, and add or remove events for
106 * its direct children. The DConfigBean implementation should not add or remove
107 * beans here if it will add or remove those beans again in response to a call to
108 * getDConfigBean or removeDConfigBean.</i></p>
109 *
110 * @see #getDConfigBean
111 * @see #removeDConfigBean
112 *
113 * @param event an event containing a reference to the DDBean which has changed.
114 */
115 public void notifyDDChange(XpathEvent event);
116
117 /**
118 * Register a property listener for this bean.
119 *
120 * @param pcl PropertyChangeListener to add
121 */
122 public void addPropertyChangeListener(PropertyChangeListener pcl);
123
124 /**
125 * Unregister a property listener for this bean.
126 *
127 * @param pcl Listener to remove.
128 */
129 public void removePropertyChangeListener(PropertyChangeListener pcl);
130 }