/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 2010 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html * or packager/legal/LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at packager/legal/LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. */ package org.glassfish.embeddable.archive; import java.io.File; import java.io.IOException; import java.net.URI; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; /** * Abstraction for a Scattered Java EE module (parts disseminated in various directories). *

*

* Usage example : *

* *

 *         GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish();
 *         glassfish.start();
 * 
 *         // Create a scattered web application.
 *         ScatteredArchive archive = new ScatteredArchive("testapp", ScatteredArchive.Type.WAR);
 *         // target/classes directory contains my complied servlets
 *         archive.addClassPath(new File("target", "classes"));
 *         // resources/sun-web.xml is my WEB-INF/sun-web.xml
 *         archive.addMetadata(new File("resources", "sun-web.xml"));
 *         // resources/MyLogFactory is my META-INF/services/org.apache.commons.logging.LogFactory
 *         archive.addMetadata(new File("resources", "MyLogFactory"),
 *                 "META-INF/services/org.apache.commons.logging.LogFactory");
 * 
 *         Deployer deployer = glassfish.getDeployer();
 *         // Deploy my scattered web application
 *         deployer.deploy(archive.toURI());
 * 
* * @author Jerome Dochez * @author bhavanishankar@java.net */ public class ScatteredArchive { String name; Type type; File rootDirectory; List classpaths = new ArrayList(); // File resourcespath; Map metadatas = new HashMap(); String metadataEntryPrefix; /** * Construct a new empty scattered archive. * * @param name name of the archive. * @param type type of the archive * @throws NullPointerException if name or type is null */ public ScatteredArchive(String name, Type type) { if (name == null) { throw new NullPointerException("name must not be null."); } if (type == null) { throw new NullPointerException("type must not be null."); } this.name = name; this.type = type; this.metadataEntryPrefix = (type == Type.WAR) ? "WEB-INF/" : "META-INF/"; } /** * Construct a new scattered archive with all the contents from the rootDirectory. *

* Follows the same semantics as {@link ScatteredArchive(String, ScatteredArchive.Type, File)} constructor. * rootDirectory must be a File location. */ // public ScatteredArchive(String name, Type type, String rootDirectory) { // this(name, type, rootDirectory != null ? new File(rootDirectory) : null); // } /** * Construct a new scattered archive with all the contents from the rootDirectory. *

* By default, a scattered archive is not different from any other * archive where all the files are located under a top level * directory (rootDirectory). *

* For example, In case of a WAR type archive, the rootDirectory should look like this: *

     *      rootDirectory/WEB-INF/classes/org/myorg/FooServlet.class
     *      rootDirectory/WEB-INF/classes/org/myorg/Bar.class
     *      rootDirectory/WEB-INF/web.xml
     *      rootDirectory/WEB-INF/lib/myjar.jar
     *      rootDirectory/index.jsp
     *      rootDirectory/theme.css
     *      rootDirectory/helper.js
     * 
* Some files can then be scattered in different locations and be specified * through the appropriate add methods of this class. *

* * @param name name of the archive. * @param type type of the archive * @param rootDirectory root directory. * @throws NullPointerException if name, type or rootDirectory is null. * @throws IOException if rootDirectory does not exist. * @throws IllegalArgumentException if rootDirectory is not a directory. */ public ScatteredArchive(String name, Type type, File rootDirectory) throws IOException { this(name, type); if (rootDirectory == null) { throw new NullPointerException("rootDirectory must not be null."); } if (!rootDirectory.exists()) { throw new IOException(rootDirectory + " does not exist."); } if (!rootDirectory.isDirectory()) { throw new IllegalArgumentException(rootDirectory + " is not a directory."); } this.rootDirectory = rootDirectory; } /** * Construct a new scattered archive with a set of classpaths. * * Follows the same semantics as * {@link ScatteredArchive(String, ScatteredArchive.Type, String, File[])} constructor. * * All classpaths[] must be File locations. */ // public ScatteredArchive(String name, Type type, String[] classpaths) { // // } /** * Construct a new scattered archive with a set of classpaths. *

* classpaths can contain Directory or JAR file locations. *

* Using this constructor has the same effect of doing: *

     *      ScatteredArchive archive = new ScatteredArchive(name, type);
     *      for(String classpath : classpaths)
     *          archive.addClassPath(classpath);
     *      }
* * @param name Name of the archive. * @param type Type of the archive "war" or "jar" or "rar". * @param classpaths Directory or JAR file locations. * @throws NullPointerException if name, type or classpaths is null * @throws IllegalArgumentException if any of the classpaths is not found. */ // public ScatteredArchive(String name, Type type, File[] classpaths) { // // } /** * Add a directory or a JAR file to this scattered archive. *

* Follows the same semantics as {@link #addClassPath(File)} method. * classpath must be a File location. */ // public void addClassPath(String classpath) { // addClassPath(classpath != null ? new File(classpath) : null); // } /** * Add a directory or a JAR file to this scattered archive. *

* The classpath that is added is considered as a plain Java CLASSPATH. *

* Case 1 : classpath is a directory: *

* Let us say there is TEMP/abc directory, which has following contents: *

     *      TEMP/abc/org/myorg/a/A.class
     *      TEMP/abc/org/myorg/b/B.class
     *      TEMP/abc/com/xyz/c/C.class
     *      TEMP/abc/LocalStrings.properties
     *      TEMP/abc/image/1.png
     * 
* then addClassPath(new File("TEMP", "abc") will make: *

* (a) The following classes available in the deployed scattered archive application: *

     *          org.myorg.a.A
     *          org.myorg.b.B
     *          com.xyz.c.C
     * 
* (b) LocalStrings.properties available in the deployed scattered archive application. * So, the deployed application can do ResourceBundle.getBundle("LocalStrings"); *

* (c) image/1.png available in the deployed scattered archive application. * So, the deployed application can load the image file via getClass().getClassLoader().getResource("image/1.png"); *

* If there is any other type of file under TEMP/abc then it will also be available * in the deployed scattered archive application's classloader. *

* Case 2: classpath is a JAR file *

* Let us say there is TEMP/xyz.jar, then addClassPath(new File("TEMP", "xyz.jar")) * will make all the classes and any random files inside TEMP/xyz.jar * available in the deployed scattered archive application. * * @param classpath A directory or a JAR file. * @throws NullPointerException if classpath is null * @throws IOException if the classpath is not found. */ public void addClassPath(File classpath) throws IOException { if (classpath == null) { throw new NullPointerException("classpath must not be null."); } if (!classpath.exists()) { throw new IOException(classpath + " does not exist."); } this.classpaths.add(classpath); } /** * Add a new metadata to this scattered archive. *

* The addMetadata(metadata) method has the same effect as: *

     *      addMetadata(metadata, null)
     * 
* Follows the same semantics as {@link #addMetadata(String, String)} method. */ // public void addMetadata(String metadata) { // addMetadata(metadata != null ? new File(metadata) : null); // } /** * Add a new metadata to this scattered archive. *

* The addMetadata(metadata) method has the same effect as: *

     *      addMetadata(metadata, null)
     * 
* Follows the same semantics as {@link #addMetadata(File, String)} method. */ public void addMetadata(File metadata) throws IOException { addMetadata(metadata, null); } /** * Add a new metadata to this scattered archive. *

* Follows the same semantics as {@link #addMetadata(File, String)} method. * metadata must be a file location. */ // public void addMetadata(String metadata, String name) { // addMetadata(metadata != null ? new File(metadata) : null, name); // } /** * Add a new metadata to this scattered archive. *

* A metadata is identified by its name (e.g., META-INF/ejb.xml). *

* If the specified name is null, then the metadata is considered as a * deployment descriptor metadata and the name is computed as: *

     *      "WEB-INF/" + metadata.getName() for WAR type archive.
     *      "META-INF/" + metadata.getName() for other type of archive.
     * 
* If the scattered archive already contains the metadata with the same name, * then the old value is replaced. * * @param metadata location of the metadata * @param name name of the metadata (e.g., * META-INF/ejb.xml or META-INF/sun-ejb-jar.xml) * @throws NullPointerException if metadata is null * @throws IOException if metadata does not exist. * @throws IllegalArgumentException if metadata is a directory. */ public void addMetadata(File metadata, String name) throws IOException { if (metadata == null) { throw new NullPointerException("metadata must not be null."); } if (!metadata.exists()) { throw new IOException(metadata + " does not exist."); } if (metadata.isDirectory()) { throw new IllegalArgumentException(metadata + " is a directory."); } if (name == null) { name = metadataEntryPrefix + metadata.getName(); } this.metadatas.put(name, metadata); } /** * Set the location of resources files to this scattered archive. *

* Follows the same semantics as {@link #setResourcePath(File)} method. * resourcespath must be a File location. */ // public void setResourcePath(String resourcespath) { // setResourcePath(resourcespath != null ? new File(resourcespath) : null); // } /** * Set the location of resources files to this scattered archive. *

* For a WAR type scattered archive, the specified resource location can be * thought of as a document root of the web application. The document root * is where JSP pages, and static web resources such as images are stored. *

* For the other type of archive, all the contents under the specified * resource location will be available in the deployed scattered * application's classloader. * * @param resourcespath Resources directory. * @throws NullPointerException if resourcepath is null. * @throws IllegalArgumentException if resourcespath is not found or is not a directory. */ // public void setResourcePath(File resourcespath) { // if (resourcespath == null) { // throw new NullPointerException("resourcespath must not be null."); // } // if (!resourcespath.exists()) { // throw new IllegalArgumentException(resourcespath + " does not exist."); // } // if (!resourcespath.isDirectory()) { // throw new IllegalArgumentException(resourcespath + " is not a directory"); // } // this.resourcespath = resourcespath; // } /** * Get the deployable URI for this scattered archive. *

* Note : java.io.tmpdir is used while building the URI. * * @return Deployable scattered archive URI. * @throws IOException if any I/O error happens while building the URI * or while reading metadata, classpath elements, rootDirectory. */ public URI toURI() throws IOException { return new Assembler().assemble(this); } /** * Enumeration values for the scattered Java EE module types. * * @author bhavanishankar@java.net */ public enum Type { /** * The module is an Enterprise Java Bean or Application Client archive. */ JAR, /** * The module is a Web Application archive. */ WAR, /** * The module is a Connector archive. */ RAR, } }