ConfigurationSupport


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.modules.j2ee.deployment.plugins.api;
21  
22  import java.io.File  ;
23  import java.util.Collections  ;
24  import java.util.HashSet  ;
25  import java.util.Set  ;
26  import javax.enterprise.deploy.model.DDBean  ;
27  import javax.enterprise.deploy.model.DeployableObject  ;
28  import javax.enterprise.deploy.spi.DeploymentConfiguration  ;
29  import javax.enterprise.deploy.spi.exceptions.ConfigurationException  ;
30  import javax.enterprise.deploy.spi.exceptions.OperationUnsupportedException  ;
31  import org.netbeans.api.project.FileOwnerQuery;
32  import org.netbeans.api.project.Project;
33  import org.netbeans.modules.j2ee.deployment.common.api.Datasource;
34  import org.netbeans.modules.j2ee.deployment.common.api.DatasourceAlreadyExistsException;
35  import org.netbeans.modules.j2ee.deployment.common.api.OriginalCMPMapping;
36  import org.netbeans.modules.j2ee.deployment.config.ConfigSupportImpl;
37  import org.netbeans.modules.j2ee.deployment.devmodules.spi.J2eeModuleProvider;
38  import org.netbeans.modules.j2ee.deployment.impl.Server;
39  import org.netbeans.modules.j2ee.deployment.impl.ServerRegistry;
40  import org.openide.filesystems.FileObject;
41  import org.openide.filesystems.FileUtil;
42  import org.openide.util.Lookup;
43  
44  
45  /**
46   * <p>
47   * ConfigurationSupport provides support for server specific configuration. It
48   * supplements the JSR-88 DeploymentConfiguration class of life cycle management 
49   * and some additional module change notifications.
50   * </p>
51   *
52   * <h3>
53   * The life cycle of the DeploymentConfiguration object.
54   * </h3>
55   *
56   * <p>
57   * When a new project is created or an existing one is opened, the j2eeserver
58   * will create a DeploymentConfiguration object for the project target server by
59   * calling DeploymentManager.createConfiguration(). After the configuration is 
60   * created, the j2eeserver will initialize it by calling ConfigurationSupport.initConfiguration().
61   * In this moment, plugin should make sure that the server specific deployment 
62   * descriptors exist and create them, if they do not. From now on the server specific
63   * deployment descriptors for the target server should be ready to respond to the 
64   * module changes.
65   * </p>
66   *
67   * <p>
68   * In case that the project target server is changed, the old server is notified
69   * by calling ConfigurationSupport.disposeConfiguration() that the old
70   * DeploymentConfiguration will be disposed, which means that the j2eeserver will
71   * release the reference to it and the configuration will be no longer receiving 
72   * notifications of the module changes. The server specific deployment descriptors for
73   * the old server will thus stop responding to the module changes.
74   * </p>
75   *
76   * <p>
77   * The life cycle for the new target server is the same as if an existing project 
78   * is opened, see above.
79   * </p>
80   *
81   * <p>
82   * In case that the target server plugin needs to have access to the initilized 
83   * deployment configuration before the j2eeserver created and initilized it by 
84   * itself, the plugin can request the j2eeserver to create and initilize it by 
85   * calling ConfigurationSupport.requestCreateConfiguration(). This may happen
86   * for example when the IDE is started and if the server specific deployment 
87   * descriptor was left open in the editor before the IDE was shutdown the last time.
88   * After calling ConfigurationSupport.requestCreateConfiguration() the life cycle 
89   * is the same as if the j2eeserver created and initialized the deployment 
90   * configuration during project opening by itself.
91   * </p>
92   *
93   * <p>
94   * In case that other than target server plugin needs to have access to the initilized 
95   * deployment configuration, the plugin can request the j2eeserver to create and 
96   * initilize the configuration by calling ConfigurationSupport.requestCreateConfiguration(). 
97   * The j2eeserver will create the configuration by calling DeploymentManager.createConfiguration() 
98   * and will initilize it by calling ConfigurationSupport.initConfiguration(), however, 
99   * with the keepUpdated=false parameter. This will tell the plugin that its server
100  * specific deployment descriptors should not respond to the module changes. In 
101  * fact, the deployment configuration will not be receiving module change events 
102  * in this case. Since the j2eeserver will not even keep a reference to this 
103  * configuration, the ConfigurationSupport.disposeConfiguration() will never be 
104  * called for this configuration, there is also no reason for it.
105  * </p>
106  *
107  *
108  * @author sherold
109  *
110  * @since 1.8
111  */
112 public abstract class ConfigurationSupport {
113     
114     /**
115      *  Setting the CMP and CMR mapping info to the given configuration for the EJB by the given name.
116      *  This call will be called after CMP wizard created all CMP beans (all new ejb events fired).
117      *
118      *  @param config   The configuration to push the CMP mapping to
119      *  @param mappings All the mapping info needed to be pushed in one batch.
120      */
121     public abstract void setMappingInfo(DeploymentConfiguration   config, 
122                                         OriginalCMPMapping[] mappings);
123     
124     /**
125      * Ensure resource is defined for the specified DD bean (for example entity bean).
126      *
127      * @param config    deployment configuration
128      * @param bean      DD bean in question
129      */
130     public abstract void ensureResourceDefined(DeploymentConfiguration   config, 
131                                                DDBean   bean);
132     
133     /**
134      * Ensure resource is defined for the specified DD bean (for example entity bean).
135      *
136      * @param config    deployment configuration
137      * @param bean      DD bean in question
138      * @param jndiName  the JNDI name of the resource where the bean is stored
139      */
140     public void ensureResourceDefined(DeploymentConfiguration   config, 
141                                                DDBean   bean, String   jndiName) {
142     }
143     
144     /**
145      * Return the context root (context path) defined for the module specified 
146      * by the deployable object.
147      *
148      * @param config  deployment configuration
149      * @param deplObj deployable object that specifies the module
150      *
151      * @return context root
152      *
153      * @throws ConfigurationException reports errors in getting the web context
154      *         root
155      */
156     public abstract String   getWebContextRoot(DeploymentConfiguration   config, 
157                                              DeployableObject   deplObj) 
158                                     throws ConfigurationException  ;
159 
160     /**
161      * Set the web context root (context path) for the module specified by the 
162      * deployable object.
163      *
164      * @param config      deployment configuration
165      * @param deplObj     deployable object that specifies the module
166      * @param contextRoot context root to be set
167      *
168      * @throws ConfigurationException reports errors in setting the web context
169      *         root
170      */
171     public abstract void setWebContextRoot(DeploymentConfiguration   config, 
172                                            DeployableObject   deplObj,
173                                            String   contextRoot) 
174                                    throws ConfigurationException  ;
175     
176     /**
177      * Initialize the specified deployment configuration. If keepUpdated is true 
178      * ensure the server specific deployment descriptors are created if they do 
179      * not exist and that they are ready to respond to the module changes. If
180      * keepUpdated is false, the module changes should not be reflected in the 
181      * server specific deployment descriptors.
182      * 
183      * @param config        the deployment configuration that should be initialized.
184      * @param files         server specific deployment configuration files.
185      * @param resourceDir   directory containing definition for enterprise resources 
186      *                      needed for the module execution or null if not supported.
187      * @param ensureCreated if keepUpdated is true ensure the server specific 
188      *                      deployment descriptors are created if they do not 
189      *                      exist and that they are ready to respond to the module 
190      *                      changes. If keepUpdated is false, the module changes 
191      *                      should not be reflected in the server specific deployment 
192      *                      descriptors.
193      *
194      * @throws ConfigurationException reports errors in deployment configuration
195      *         initialization.
196      */
197     public abstract void initConfiguration(DeploymentConfiguration   config, 
198                                            File  [] files, 
199                                            File   resourceDir, 
200                                            boolean keepUpdated) 
201                                     throws ConfigurationException  ;
202     
203     /**
204      * The specified deployment configuration instance is about to be disposed,
205      * which means that the j2eeserver will release the reference to it and the 
206      * configuration will be no longer receiving notifications of the module changes.
207      *
208      * @param config deployment configuration which is about to be disposed.
209      */
210     public abstract void disposeConfiguration(DeploymentConfiguration   config);
211     
212     /**
213      * <p>
214      * Request the j2eeserver to create and initialize the deployment configuration
215      * for the specified server and module the given server specific deployment 
216      * descriptor file belongs to. If the deployment configuration has already 
217      * been created nothing will happen, otherwise a new instance will be created 
218      * by calling DeploymentManager.createConfiguration() and then initialized by 
219      * calling ConfigurationSupport.initConfiguration().
220      * </p>
221      *
222      * <p>
223      * The j2eeserver creates and initializes the deployment configuration for the
224      * server that is set as a target server for the given module. In some cases,
225      * however, the data object representing the server specific deployment descriptor
226      * may require access to the initialized deployment configuration even before
227      * the configuration is created and initialized by the j2eeserver itself. This
228      * may happen for instance when the server specific deployment descriptor is
229      * being reopened during the IDE startup if it was left open before the IDE 
230      * was shut down the last time.
231      * </p>
232      *
233      * @param fo        server specific deployment descriptor file object
234      * @param serverID  server (plugin) ID
235      */
236     public static final void requestCreateConfiguration(FileObject fo, 
237                                                         String   serverID) 
238                                             throws ConfigurationException   {
239         Project project = FileOwnerQuery.getOwner(fo);
240         if (project == null) {
241             throw new ConfigurationException  ("File " + FileUtil.toFile(fo).getAbsolutePath() + " is not part of any project"); // NOI18N
242         }
243         Lookup l = project.getLookup();
244         J2eeModuleProvider moduleProvider = (J2eeModuleProvider)l.lookup(J2eeModuleProvider.class);
245         if (moduleProvider == null) {
246             throw new ConfigurationException  ("Project " + project + " does not provide J2eeModuleProvider in its lookup"); // NOI18N
247         }
248         Server server = ServerRegistry.getInstance().getServer(serverID);
249         ConfigSupportImpl conf = (ConfigSupportImpl)moduleProvider.getConfigSupport();
250         conf.createDeploymentConfiguration(server);
251     }
252     
253     /**
254      * Update the enterprise resource directory for the specified deployment
255      * configuration.
256      *
257      * @param config      deployment configuration
258      * @param resourceDir new enterprise resource directory.
259      * @since 1.12
260      */
261     public abstract void updateResourceDir(DeploymentConfiguration   config, File   resourceDir);
262     
263     /**
264      * Gets the data sources saved in the module.
265      *
266      * @param config deployment configuration
267      * @return a set of data sources. The default implementation returns an empty set.
268      *
269      * @since 1.15
270      */
271     public Set  <Datasource> getDatasources(DeploymentConfiguration   config) {
272         return Collections.<Datasource>emptySet();
273     }
274     
275     /**
276      * Tests whether data source creation is supported.
277      *
278      * @return true if data source creation is supported. The default implementation returns false.
279      *
280      * @since 1.15
281      */
282     public boolean isDatasourceCreationSupported() {
283         return false;
284     }
285             
286     /**
287      * Creates and saves data source in the module if it does not exist yet in the module.
288      * Data source is considered to be existing when JNDI name of the found data source and the one
289      * just created equal.
290      *
291      * @param config deployment configuration
292      * @param jndiName name of data source
293      * @param url database URL
294      * @param username database user
295      * @param password user's password
296      * @param driver fully qualified name of the database driver class
297      * @return created data source
298      * @exception OperationUnsupportedException if operation is not supported
299      * @exception ConfigurationException if data source configuration file is not parseable
300      * @exception DatasourceAlreadyExistsException if conflicting data source is found
301      *
302      * @since 1.15
303      */
304     public Datasource createDatasource(DeploymentConfiguration   config, String   jndiName, String    url, String   username, String   password, String   driver) 
305     throws OperationUnsupportedException  , ConfigurationException  , DatasourceAlreadyExistsException
306     {
307         throw new OperationUnsupportedException  (""); // NOI18N
308     }
309 }
310
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags