001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.enterprise.deploy.spi;
027    
028    import javax.enterprise.deploy.model.DDBean;
029    import javax.enterprise.deploy.model.XpathEvent;
030    import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
031    import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;
032    import java.beans.PropertyChangeListener;
033    
034    /**
035     * The interface for configuring a server-specific deployment descriptor, or subset of same.
036     * A DConfigBean corresponds to a specific location in a standard deployment descriptor,
037     * typically where values (such as names and roles) are used.
038     *
039     * <p>There are three different ways that DConfigBeans are created:</p>
040     *
041     * <ul>
042     *   <li><code>DeploymentConfigurator.getDConfigBean(DDBeanRoot)</code> is called by the
043     *       deployment tool to create a DConfigBeanRoot for each deployment descriptor in
044     *       the J2EE application.</li>
045     *   <li><code>DConfigBean.getDConfigBean(DDBean)</code> is called by the deployment
046     *       tool for each DDBean that corresponds to a relative XPath pattern given to the
047     *       deployment tool by the method <code>DConfigBean.getXpaths()</code>.</li>
048     *   <li>Each DConfigBean can structure its configurations as a tree-structure of
049     *       DConfigBeans; a DConfigBean can have properties of type DConfigBean or
050     *       DConfigBean[].</li>
051     * <ul>
052     *
053     * <p>The properties of DConfigBeans are displayed and edited by the deployment tool by
054     * using the JavaBean Property classes.</p>
055     *
056     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
057     */
058    public interface DConfigBean {
059        /**
060         * Return the JavaBean containing the deployment descriptor XML text associated with this DConfigBean.
061         *
062         * @return The bean class containing the XML text for this DConfigBean.
063         */
064        public DDBean getDDBean();
065    
066        /**
067         * Return a list of XPaths designating the deployment descriptor information this
068         * DConfigBean requires.  Each server vendor may need to specify different
069         * server-specific information.  Each String returned by this method is an XPath
070         * describing a certain portion of the standard deployment descriptor for which
071         * there is corresponding server-specific configuration.
072         *
073         * @return a list of XPath Strings representing XML data to be retrieved or
074         *         <code>null</code> if there are none.
075         */
076        public String[] getXpaths();
077    
078        /**
079         * Return the JavaBean containing the server-specific deployment configuration
080         * information based upon the XML data provided by the DDBean.
081         *
082         * @param bean The DDBean containing the XML data to be evaluated.
083         *
084         * @return The DConfigBean to display the server-specific properties for the standard bean.
085         *
086         * @throws ConfigurationException reports errors in generating a configuration bean.
087         *         This DDBean is considered undeployable to this server until this exception is
088         *         resolved.  A suitably descriptive message is required so the user can diagnose
089         *         the error.
090         */
091        public DConfigBean getDConfigBean(DDBean bean) throws ConfigurationException;
092    
093        /**
094         * Remove a child DConfigBean from this bean.
095         *
096         * @param bean The child DConfigBean to be removed.
097         *
098         * @throws BeanNotFoundException the bean provided is not in the child list of this bean.
099         */
100        public void removeDConfigBean(DConfigBean bean) throws BeanNotFoundException;
101    
102        /**
103         * A notification that the DDBean provided in the event has changed and this bean
104         * or its child beans need to reevaluate themselves.
105         *
106         * <p><i>It is advisable, though not declared explicitly in the specification, for a
107         * DConfigBean to receive change events for itself, and add or remove events for
108         * its direct children.  The DConfigBean implementation should not add or remove
109         * beans here if it will add or remove those beans again in response to a call to
110         * getDConfigBean or removeDConfigBean.</i></p>
111         *
112         * @see #getDConfigBean
113         * @see #removeDConfigBean
114         *
115         * @param event an event containing a reference to the DDBean which has changed.
116         */
117        public void notifyDDChange(XpathEvent event);
118    
119        /**
120         * Register a property listener for this bean.
121         *
122         * @param pcl PropertyChangeListener to add
123         */
124        public void addPropertyChangeListener(PropertyChangeListener pcl);
125    
126        /**
127         * Unregister a property listener for this bean.
128         *
129         * @param pcl Listener to remove.
130         */
131        public void removePropertyChangeListener(PropertyChangeListener pcl);
132    }