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.DeployableObject;
029    import javax.enterprise.deploy.model.DDBeanRoot;
030    import javax.enterprise.deploy.spi.exceptions.ConfigurationException;
031    import javax.enterprise.deploy.spi.exceptions.BeanNotFoundException;
032    import java.io.OutputStream;
033    import java.io.InputStream;
034    
035    /**
036     * An interface that defines a container for all the server-specific configuration
037     * information for a single top-level J2EE module.  The DeploymentConfiguration
038     * object could represent a single stand alone module or an EAR file that contains
039     * several sub-modules.
040     *
041     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
042     */
043    public interface DeploymentConfiguration {
044        /**
045         * Returns an object that provides access to the deployment descriptor data
046         * and classes of a J2EE module.
047         *
048         * @return A DeployableObject
049         */
050        public DeployableObject getDeployableObject();
051    
052        /**
053         * Returns the top level configuration bean, DConfigBeanRoot, associated with
054         * the deployment descriptor represented by the designated DDBeanRoot bean.
055         *
056         * @param bean The top level bean that represents the associated deployment descriptor.
057         *
058         * @return the DConfigBeanRoot for editing the server-specific properties required by the module.
059         *
060         * @throws ConfigurationException reports errors in generating a configuration bean
061         */
062        public DConfigBeanRoot getDConfigBeanRoot(DDBeanRoot bean) throws ConfigurationException;
063    
064        /**
065         * Remove the root DConfigBean and all its children.
066         *
067         * @param bean the top leve DConfigBean to remove.
068         *
069         * @throws BeanNotFoundException the bean provided is not in this beans child list.
070         */
071        public void removeDConfigBean(DConfigBeanRoot bean) throws BeanNotFoundException;
072    
073        /**
074         * Restore from disk to instantated objects all the DConfigBeans associated with a
075         * specific deployment descriptor. The beans may be fully or partially configured.
076         *
077         * @param inputArchive The input stream for the file from which the DConfigBeans
078         *                     should be restored.
079         * @param bean         The DDBeanRoot bean associated with the deployment descriptor file.
080         *
081         * @return The top most parent configuration bean, DConfigBeanRoot
082         *
083         * @throws ConfigurationException reports errors in generating a configuration bean
084         */
085        public DConfigBeanRoot restoreDConfigBean(InputStream inputArchive, DDBeanRoot bean) throws ConfigurationException;
086    
087        /**
088         * Save to disk all the configuration beans associated with a particular deployment
089         * descriptor file. The saved data may be fully or partially configured DConfigBeans.
090         * The output file format is recommended to be XML.
091         *
092         * @param outputArchive The output stream to which the DConfigBeans should be saved.
093         * @param bean          The top level bean, DConfigBeanRoot, from which to be save.
094         *
095         * @throws ConfigurationException reports errors in storing a configuration bean
096         */
097        public void saveDConfigBean(OutputStream outputArchive, DConfigBeanRoot bean) throws ConfigurationException;
098    
099        /**
100         * Restore from disk to a full set of configuration beans previously stored.
101         *
102         * @param inputArchive The input stream from which to restore the Configuration.
103         *
104         * @throws ConfigurationException reports errors in generating a configuration bean
105         */
106        public void restore(InputStream inputArchive) throws ConfigurationException;
107    
108        /**
109         * Save to disk the current set configuration beans created for this deployable
110         * module.  It is recommended the file format be XML.
111         *
112         * @param outputArchive The output stream to which to save the Configuration.
113         *
114         * @throws ConfigurationException reports errors in storing a configuration bean
115         */
116        public void save(OutputStream outputArchive) throws ConfigurationException;
117    }