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.model;
027    
028    import java.io.FileNotFoundException;
029    import java.io.InputStream;
030    import java.util.Enumeration;
031    import javax.enterprise.deploy.model.exceptions.DDBeanCreateException;
032    import javax.enterprise.deploy.shared.ModuleType;
033    
034    /**
035     * The DeployableObject interface is an abstract representation of a J2EE deployable
036     * module (JAR, WAR, RAR, EAR).  A DeployableObject provides access to the module's
037     * deployment descriptor and class files.
038     *
039     * @version $Rev: 467553 $ $Date: 2006-10-25 06:01:51 +0200 (Mi, 25. Okt 2006) $
040     */
041    public interface DeployableObject {
042        /**
043         * Return the ModuleType of deployment descriptor (i.e., EAR, JAR, WAR, RAR)
044         * this deployable object represents. Values are found in DeploymentManager.
045         *
046         * @return The ModuleType of deployable object
047         */
048        public ModuleType getType();
049    
050        /**
051         * Return the top level standard bean representing the root of the deployment descriptor.
052         *
053         * @return A standard bean representing the deployment descriptor.
054         */
055        public DDBeanRoot getDDBeanRoot();
056    
057        /**
058         * Return an array of standard beans representing the XML content returned based upon the XPath.
059         *
060         * @param xpath AAn XPath string identifying the data to be extracted from the deployment descriptor.
061         *
062         * @return an array of DDBeans or <code>null</code> if no matching data is found.
063         */
064        public DDBean[] getChildBean(String xpath);
065    
066        /**
067         *
068         * @param xpath An xpath string referring to a location in the deployment descriptor
069         *
070         * @return a list XML content or <code>null</code> if no matching data is found.
071         */
072        public String[] getText(String xpath);
073    
074        /**
075         * Retrieve the specified class from this deployable module.
076         * <p>One use: to get all finder methods from an EJB.  If the tool is attempting to package a
077         * module and retrieve a class from the package, the class request may fail. The class may
078         * not yet be available. The tool should respect the manifest Class-Path entries.</p>
079         *
080         * @param className Class to retrieve.
081         *
082         * @return Class representation of the class
083         */
084        public Class getClassFromScope(String className);
085    
086        /**
087         * A convenience method to return the deployment descriptor
088         * document version number of the primary deployment descriptor
089         * for the module (e.g. web.xml, ejb-jar.xml, ra.xml, application.xml,
090         * and  application-client.xml.)  The version number for documents
091         * webservices.xml , webservicesclient.xml and the like are not returned
092         * by this method.  DDBeanRoot.getDDBeanRootVersion should be used
093         * instead.
094         *
095         * This method is being deprecated.  DDBeanRoot.getDDBeanRootVersion
096         * should be used instead.
097         *
098         * @deprecated As of version 1.1, replace by DDBeanRoot.getDDBeanRootVersion()
099         *
100         * @return a string that is the version number of the XML instance document.
101         *  Null is returned if no version number can be found.
102         */
103        public String getModuleDTDVersion();
104    
105        /**
106         * Returns a DDBeanRoot object for the XML instance document named.
107         * This method should be used to return DDBeanRoot objects for non deployment
108         * descriptor XML instance documents such as WSDL files.
109         *
110         * @since 1.1
111         *
112         * @param filename the full path name from the root of the module of the xml
113         *        instance document for which a DDBeanRoot object is to be returned.
114         *
115         * @return a DDBeanRoot object for the XML data.
116         *
117         * @throws java.io.FileNotFoundException if the named file can not be found
118         * @throws javax.enterprise.deploy.model.exceptions.DDBeanCreateException
119         *         if an error is encountered creating the DDBeanRoot object.
120         */
121        public DDBeanRoot getDDBeanRoot(String filename) throws FileNotFoundException, DDBeanCreateException;
122    
123        /**
124         * Returns an enumeration of the module file entries.  All elements in the
125         * enumeration are of type String.  Each String represents a file name relative
126         * to the root of the module.
127         *
128         * @since 1.1
129         *
130         * @return an enumeration of the archive file entries.
131         */
132        public Enumeration entries();
133    
134        /**
135         * Returns the InputStream for the given entry name.
136         * The file name must be relative to the root of the module.
137         *
138         * @since 1.1
139         *
140         * @param name the file name relative to the root of the module.
141         *
142         * @return the InputStream for the given entry name or null if not found.
143         */
144        public InputStream getEntry(String name);
145    }