001 /**
002 *
003 * Copyright 2003-2004 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 //
019 // This source code implements specifications defined by the Java
020 // Community Process. In order to remain compliant with the specification
021 // DO NOT add / change / or delete method signatures!
022 //
023
024 package javax.enterprise.deploy.spi;
025
026 import javax.enterprise.deploy.model.DDBean;
027 import javax.enterprise.deploy.model.XpathEvent;
028 import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
029 import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;
030 import java.beans.PropertyChangeListener;
031
032 /**
033 * The interface for configuring a server-specific deployment descriptor, or subset of same.
034 * A DConfigBean corresponds to a specific location in a standard deployment descriptor,
035 * typically where values (such as names and roles) are used.
036 *
037 * <p>There are three different ways that DConfigBeans are created:</p>
038 *
039 * <ul>
040 * <li><code>DeploymentConfigurator.getDConfigBean(DDBeanRoot)</code> is called by the
041 * deployment tool to create a DConfigBeanRoot for each deployment descriptor in
042 * the J2EE application.</li>
043 * <li><code>DConfigBean.getDConfigBean(DDBean)</code> is called by the deployment
044 * tool for each DDBean that corresponds to a relative XPath pattern given to the
045 * deployment tool by the method <code>DConfigBean.getXpaths()</code>.</li>
046 * <li>Each DConfigBean can structure its configurations as a tree-structure of
047 * DConfigBeans; a DConfigBean can have properties of type DConfigBean or
048 * DConfigBean[].</li>
049 * <ul>
050 *
051 * <p>The properties of DConfigBeans are displayed and edited by the deployment tool by
052 * using the JavaBean Property classes.</p>
053 *
054 * @version $Rev: 46019 $ $Date: 2004-09-14 02:56:06 -0700 (Tue, 14 Sep 2004) $
055 */
056 public interface DConfigBean {
057 /**
058 * Return the JavaBean containing the deployment descriptor XML text associated with this DConfigBean.
059 *
060 * @return The bean class containing the XML text for this DConfigBean.
061 */
062 public DDBean getDDBean();
063
064 /**
065 * Return a list of XPaths designating the deployment descriptor information this
066 * DConfigBean requires. Each server vendor may need to specify different
067 * server-specific information. Each String returned by this method is an XPath
068 * describing a certain portion of the standard deployment descriptor for which
069 * there is corresponding server-specific configuration.
070 *
071 * @return a list of XPath Strings representing XML data to be retrieved or
072 * <code>null</code> if there are none.
073 */
074 public String[] getXpaths();
075
076 /**
077 * Return the JavaBean containing the server-specific deployment configuration
078 * information based upon the XML data provided by the DDBean.
079 *
080 * @param bean The DDBean containing the XML data to be evaluated.
081 *
082 * @return The DConfigBean to display the server-specific properties for the standard bean.
083 *
084 * @throws ConfigurationException reports errors in generating a configuration bean.
085 * This DDBean is considered undeployable to this server until this exception is
086 * resolved. A suitably descriptive message is required so the user can diagnose
087 * the error.
088 */
089 public DConfigBean getDConfigBean(DDBean bean) throws ConfigurationException;
090
091 /**
092 * Remove a child DConfigBean from this bean.
093 *
094 * @param bean The child DConfigBean to be removed.
095 *
096 * @throws BeanNotFoundException the bean provided is not in the child list of this bean.
097 */
098 public void removeDConfigBean(DConfigBean bean) throws BeanNotFoundException;
099
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 }