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 }