1. Introduction 1.1. Project/Component Working Name: GlassFish v3 File Layout 1.2. Name(s) and e-mail address of Document Author(s)/Supplier: Snjezana Sevo-Zenzerovic: snjezana.sevo-zenzerovic@sun.com 1.3. Date of This Document: 12/01/2009 2. Project Summary 2.1. Project Description: This project defines product file layout used to deliver the content of GlassFish v3 release as standalone product distribution. 2.2. Risks and Assumptions: Projects assumes that other product features such as OSGi framework integration are able to support file layout proposed in this specification and are also flexible enough to support file layout changes required for alternative distributions such as native package based distributions. 3. Problem Summary 3.1. Problem Area: GlassFish v3 release has to be delivered as standalone product installation integrated into Update Center 2.x content delivery mechanism based on Image Packaging System (IPS). Product must have well defined file layout interface which both supports existing product functionality and enables the delivery of additional functional modules. 3.2. Justification: File layout is essential product interface. 4. Technical Description: 4.1. Details: Product file layout will be largely based on WSARC 2006/239 (Filesystem Layout for Unbundled Software: Best Practices and Requirements). Intent is to keep GlassFish implementation flexible enough to allow for changes in file layout which would enable the delivery of other distributions (see section 4.4 for more details) but only file layout for standalone GlassFish distribution will be specified in this document. 4.2. Bug/RFE Number(s): N/A 4.3. In Scope: File layout for standalone IPS image based distributions of GlassFish v3 release. This includes web profile distribution, full distribution and RI distribution. 4.4. Out of Scope: File layout for any other distributions based on GlassFish v3 release and file layout for additional product functionality delivered in subsequent GlassFish v3 update releases. This includes potential delivery of GlassFish v3 in native package formats such as SVR4, RPM, Debian and bundling of GlassFish into platform distributions based on such packaging formats. In those scenarios GlassFish file layout will need to follow specific distribution file layout rules and will be covered in separate specification documents as needed. 4.5. Interfaces: 4.5.1 Exported Interfaces Interface: GlassFish v3 File Layout Stability: Uncommitted Former Stability (if changing): N/A Comments: Described in section 4.5.1.1 Interface: asenv.[conf|bat] Configuration File Stability: Uncommitted Former Stability (if changing): N/A Comments: Described in section 4.5.1.2 4.5.1.1 GlassFish v3 File Layout Default installation directories are: $HOME/glassfishv3 (non-Windows platforms) :\glassfishv3 (Windows platforms) User can override default installation directories by providing alternative value to installer or by extracting the zip distribution in different location. Selected installation directory is referenced as in the remainder of this document. File layout for standalone GlassFish v3 distributions: bin/ Wrappers/links to commonly used utilities (asadmin, pkg, updatetool) glassfish/ GlassFish bin/ Public utilities (asadmin, startserv, stopserv) config/ Installation-wide configuration files icons/ Icon files (installer distribution only) lib/ appclient/ Standalone client support files dtds/ DTD files embedded/ Embedded shell jar files endorsed/ Endorsed jar files install/applications/ RA files, Admin GUI install/templates/ OS service and resource templates monitor/ Monitoring (btrace) client jar files registration/ Service tag registry schemas/ Schema files templates/ Template files modules/ Module libraries autostart/ Modules loaded by Felix fileinstall endorsed/ Endorsed module libraries docs/ Bundled documentation files domains/ Domain configurations domain1/ Default domain configuration applications/ Deployed applications autodeploy/ Autodeploy directory bin/ config/ Domain configuration files classes/ Domain specific classes docroot/ Default docroot lib/ Domains specific libraries ext/ logs/ Log files osgi-cache/ felix/ Felix cache directory legal/ Legal files (licenses, copyright) osgi/ OSGi framework files felix/ Felix OSGi framework bin/ conf/ equinox/ configuration/ Equinox (configuration only) javadb/ JavaDB mq/ Message Queue (full distribution only) pkg/ IPS CLI client updatetool/ UC 2.x GUI client .org.opensolaris,pkg/ IPS package database (hidden directory) 4.5.1.2 asenv.[conf|bat] Configuration File asenv file is configuration file containing installation locations of those components which are either delivered separately of GlassFish distribution or can be expected to be installed outside of distribution installation directory in the case of GlassFish distributions delivered in OS bundled scenario. GlassFish should, however, continue to function for the default use case where asenv file contains default values or relative locations and GlassFish is delivered as zip archive distribution. In other use cases, asenv file will be updated with alternative values either as part of install time configuration, or asenv file with prepopulated alternative values will be shipped as part of particular distribution. asenv file name/location: /config/asenv.conf (non-Windows platforms) \config\asenv.bat (Windows platforms) asenv variables: AS_INSTALL - defines GlassFish installation directory AS_CONFIG - defines GlassFish configuration directory AS_DEF_DOMAINS_PATH - defines GlassFish default domain configuration directory; override use case for standalone distribution is to enable proper functioning on Windows systems with enabled User Access Control feature AS_DERBY_INSTALL - defines JavaDB installation directory AS_IMQ_BIN - defines the location of MQ utilities AS_IMQ_LIB - defines the location of MQ libraries AS_JAVA - defines JDK installation directory; if undefined GlassFish falls back on system environment variable PATH FELIX_HOME - defines Felix installation directory; if undefined it falls back on the default location glassfish/osgi/felix Default asenv.conf content: AS_INSTALL=".." AS_CONFIG="../config" AS_DEF_DOMAINS_PATH="../domains" AS_DERBY_INSTALL="../../javadb" AS_IMQ_LIB="../../mq/lib" AS_IMQ_BIN="../../mq/bin" Default asenv.bat content: set AS_INSTALL=.. set AS_CONFIG=..\config set AS_DEF_DOMAINS_PATH=..\domains set AS_DERBY_INSTALL=..\..\javadb set AS_IMQ_LIB=..\..\mq\lib set AS_IMQ_BIN=..\..\mq\bin 4.5.2 Imported interfaces Interface: Filesystem Layout for Unbundled Software Stability: Committed Exporting Project: WSARC 2006/239 http://sac.sfbay.sun.com/Archives/CaseLog/arc/WSARC/2006/239/final.m aterials/FSL_Unbundled_v1.0.pdf Comments: Only Sun internal link available at this time. 4.6. Doc Impact: This project impacts all product documentation since it defines product file layout and naming. 4.7. Admin/Config Impact: Project defines the location of product files, including those used for product configuration. 4.8. HA Impact: N/A 4.9. I18N/L10N Impact: Additional localized content will be delivered following Java and OSGi guidelines and its file layout will match the layout of corresponding base content. 4.10. Packaging & Delivery: This feature will be delivered as part of standalone GlassFish v3 distributions. 4.11. Security Impact: Security considerations will be taken into account while specifying default file/directory access permissions. 4.12. Compatibility Impact Several file layout changes compared to previous major release (GlassFish v2): * Standalone distributions contain glassfish subdirectory in order to comply with unbundled software file layout policy and enable integration with Update Center 2.0. * Product libraries are moved from lib to modules subdirectory. This will be mitigated by providing "wrapper" jar files for javaee.jar, j2ee.jar and appserv-rt.jar in glassfish/lib directory in order to retain backward compatibility. * Addition of dedicated legal directory for legal files (previously installed in top level product directory). * Addition of osgi directory as the result of OSGi integration. * Message Queue installed in top level director instead of being installed into subdirectory. * JavaDB installed in top level directory instead of being installed into subdirectory. 4.13. Dependencies: Proposal depends on the delivery of all GlassFish v3 release product components and it is sensitive to changes in product content. 5. Reference Documents: In addition to imported interface documents referenced in section 4.5.2. following documents are of interest: * OSGi Integration One-pager http://wiki.glassfish.java.net/Wiki.jsp?page=V3FunctionalSpecs 6. Schedule: 6.1. Projected Availability: December 2009