This section describes the different ways to deploy Java EE modules to the Enterprise Server. It covers the following topics:
If an error occurs during deployment, the module is not deployed. This prevents a partial deployment that could leave the server in an inconsistent state.
In addition, certain warning conditions allow a module to be deployed but return a warning message to the deployment client.
After installing the Enterprise Server and starting a domain, you can deploy (install) Java EE modules. During deployment and as the application is changed, a module can go through the following stages:
Initial Deployment
Before deploying a module, start the domain.
Because modules are packaged in archive files, specify the archive file name during deployment.
Deployment is dynamic: you don’t need to restart the server after deploying a module. If you do restart, all deployed modules are still deployed and available.
Enabling or Disabling
By default, a deployed module is enabled, which means that it is runnable. To prevent access, disable the application or module. A disabled module is not uninstalled from the domain and can be easily enabled after deployment. For more information, see Disabling a Deployed Application or Module.
To replace a deployed module, redeploy it. Redeploying automatically undeploys the previously deployed module and replaces it with the new one.
Undeployment
To uninstall a module, undeploy it.
This section covers the following topics related to deployment for development:
You can overwrite a previously deployed module by using the asadmin redeploy command, the --force option of asadmin deploy, or the Redeploy button in the Administration Console. However, you must remove a preconfigured resource before you can update it.
You can deploy, redeploy, and undeploy a module without restarting the server. This is called dynamic deployment. Although primarily for developers, dynamic deployment can be used in operational environments to bring new applications and modules online without requiring a server restart.
Whenever a redeployment is done, the sessions at that transit time become invalid unless you use the keepSessions=true property of the asadmin redeploy command. For example:
asadmin redeploy --properties keepSessions=true --name hello.war |
For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
Keep Sessions is also a checkbox option when you redeploy using the Administration Console. For details, click the Help button in the Administration Console.
You can disable a deployed module without removing it from the server. Disabling a module makes it inaccessible to clients.
To disable a module using the asadmin disable command, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
Open the Applications component.
Go to the page for the type of module.
For example, for a web application, go to the Web Applications page.
Click on the box to the left of the name of each module you wish to disable.
Click on the Disable button.
For details, click the Help button in the Administration Console.
If dynamic reloading is enabled (it is by default), you do not have to redeploy a module when you change its code or deployment descriptors. Simply copy the changed class files or descriptors into the deployment directory for the module. Then update the timestamp of a file named .reload as described in To Reload Code or Deployment Descriptor Changes. The server checks for changes periodically and redeploys the module, automatically and dynamically, with the changes. Deployment directories are as follows:
domain-dir/applications/module-name
Deployment directories may change between Enterprise Server releases.
Dynamic reloading is useful in a development environment, because it allows code changes to be tested quickly. In a production environment, however, dynamic reloading might degrade performance. In addition, whenever a reload is done, the sessions at that transit time become invalid. The client must restart the session. JSP file changes don't need to be dynamically reloaded. Modified JSP files are automatically recompiled and reloaded when they are accessed.
Select the Application Server component.
Select the Advanced tab.
Select the Applications Configuration tab.
Check the Reload Enabled box to enable dynamic reloading.
Enter a number of seconds in the Reload Poll Interval field.
This sets the interval at which modules are checked for code changes and dynamically reloaded. The default is 2.
For details, click the Help button in the Administration Console.
Create an empty file named .reload at the root of the deployed module.
domain-dir/applications/module-name/.reload
Deployment directories may change between Enterprise Server releases.
Explicitly update the .reload file’s timestamp (touch .reload in UNIX) each time you make changes.
Automatic deployment, also called autodeployment, involves copying a module file (JAR, WAR) into a special directory, where it is automatically deployed by the Enterprise Server. To undeploy an automatically deployed module, simply remove its file from the special autodeployment directory. This is useful in a development environment, because it allows new code to be tested quickly. Autodeployment is enabled by default.
Autodeployment of a web services JSR 181 annotated file is supported. For more information, see JSR 181 and Chapter 5, Developing Web Services, in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.
Autodeployment is enabled by default.
Select the Application Server component.
Select the Advanced tab.
Select the Applications Configuration tab.
Check the Auto Deploy Enabled box to enable autodeployment, or uncheck this box to disable autodeployment.
Enter a number of seconds in the Auto Deploy Poll Interval field.
This sets the interval at which modules are checked for code changes and dynamically reloaded. The default is 2.
You can change the Auto Deploy Directory.
You can enter an absolute or relative path. A relative path is relative to domain-dir. The default is domain-dir/autodeploy.
Check the Precompile Enabled box to precompile any JSP files.
For details, click the Help button in the Administration Console.
A directory containing an unpackaged module is sometimes called an exploded directory. To deploy a directory instead of an EAR or WAR, you can do one of the following:
Use the Administration Console as described in The Administration Console Deployment Pages and enter a path to an exploded directory instead of a path to an archive file.
Use the asadmin deploy command and specify a path to an exploded directory instead of a path to an archive file. See the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
The contents of the directory must match the contents of a corresponding Java EE archive file. For example, if you deploy a Web application from a directory, the contents of the directory must be the same as a corresponding WAR file. In addition, the directories holding the modules must be named with _jar and _war suffixes. For information about the required directory contents, see the appropriate specifications.
The directory must be accessible to the machine on which the Enterprise Server runs.
You can change the deployment descriptor files directly in the exploded directory. If your environment is configured to use dynamic reloading, you can also dynamically reload modules deployed from the directory. For more information, see Dynamic Reloading.
On Windows, if you are deploying a directory on a mapped drive, you must be running the Enterprise Server as the same user to which the mapped drive is assigned, or the Enterprise Server won’t see the directory.
This section discusses the various tools that can be used to deploy modules and applications. The deployment tools include:
You can use the following asadmin commands to deploy or undeploy web or EJB modules on local servers.
deploy — Deploys a web or EJB module. If the module is already deployed, you can force redeployment by setting the --force option to true. You can also deploy a module in an expanded directory structure. See Directory Deployment.
redeploy — Redeploys a web or EJB module that is already deployed. Whenever a redeployment is done, the sessions at that transit time become invalid unless you use the keepSessions=true property of the asadmin redeploy command.
disable — Immediately disables a web or EJB module. Disabling a web module makes it inaccessible to clients.
deploydir — Deploys a web or EJB module from an expanded directory structure. Deprecated; use asadmin deploy instead.
For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
You can use the Administration Console to deploy modules to both local and remote Enterprise Server sites.
Open the Applications component.
Go to the page for the type of application or module.
For example, for a web application, go to the Web Applications page. You can undeploy, enable, or disable an application or module from the table on this page.
Click on the Deploy button.
On this page, you type the path to the WAR, JAR, or the exploded directory structure. You can also specify deployment settings that vary according to the type of module.
For details, click the Help button in the Administration Console.
For more information on deploying from an exploded directory structure, see Directory Deployment.
Web services are not supported unless the optional Metro (JSR 109) add-on component is downloaded from the Update Tool. Without the Metro component, a servlet or EJB module cannot be a web service endpoint, and the sun-web.xml and sun-ejb-jar.xml elements related to web services are ignored.
For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.
You deploy a web service endpoint to the Enterprise Server just as you would any servlet or stateless session bean (SLSB).
Web service management is fully supported in the Administration Console. If the deployed module has a web service endpoint, it is detected automatically during deployment. Once the module is deployed, click on the Web Service component. The table in the right frame lists deployed web service endpoints.
You can use the --registryjndiname option of the asadmin deploy command to publish the web service as part of deployment, but this is optional. See Tools for Deployment.
To deploy a JSR 181 annotated file, use the autodeployment feature. You can compile and deploy in one step, as in the following example:
javac -cp javaee.jar -d domain-dir/autodeploy MyWS.java |
For more information about JSR 181, see http://jcp.org/en/jsr/detail?id=181. For more information about autodeployment, see Automatic Deployment.
The Sun-specific deployment descriptor files sun-web.xml and sun-ejb-jar.xml provide optional web service enhancements in their webservice-endpoint and webservice-description elements.
For more information about web services, see JSR 181 and Chapter 5, Developing Web Services, in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.
You deploy a WAR module as described in Tools for Deployment. If you do not specify a context root, the default is the name of the WAR file without the extension.
If a web application accesses a DataSource that is not specified in a resource-ref in sun-web.xml, or there is no sun-web.xml file, the resource-ref-name defined in web.xml is used. A warning message is logged recording the JNDI name used to look up the resource.
You can precompile JSP files during deployment by checking the appropriate box in the Administration Console, or by using the --precompilejsp option of the asadmin deploy command.
You can keep the generated source for JSP files by adding the keepgenerated flag to the jsp-config element in sun-web.xml. For example:
<sun-web-app> ... <jsp-config> <property name=keepgenerated value=true /> </jsp-config> </sun-web-app>
If you include this property when you deploy the WAR module, the generated source is kept in domain-dir/generated/jsp/module-name.
For more information about JSP precompilation, see jsp-config.
If you deploy a web application and don't specify any assigned virtual servers, the web application is assigned to all currently defined virtual servers. If you then create additional virtual servers and want to assign existing web applications to them, you must redeploy the web applications. For more information about virtual servers, see virtual-server in Sun GlassFish Enterprise Server v3 Prelude Administration Reference.
Whenever a redeployment is done, the sessions at that transit time become invalid unless you use the keepSessions=true property of the asadmin redeploy command. For example:
asadmin redeploy --properties keepSessions=true --name hello.war |
For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
Keep Sessions is also a checkbox option when you redeploy using the Administration Console. For details, click the Help button in the Administration Console.
Web module context roots must be unique within the server.
For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. Only stateless session beans with local interfaces and entity beans that use the Java Persistence API are supported. Stateful, message-driven, and EJB 2.0 and 2.1 entity beans are not supported. Remote interfaces and remote business interfaces for any of the bean types are not supported. The sun-ejb-jar.xml elements related to these features are ignored.
For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.
You deploy an EJB JAR module as described in Tools for Deployment.
If no JNDI name for the EJB JAR module is specified in the jndi-name element immediately under the ejb element in sun-ejb-jar.xml, or there is no sun-ejb-jar.xml file, a default, non-clashing JNDI name is derived. A warning message is logged recording the JNDI name used to look up the EJB JAR module.
When Java EE applications and modules use shared framework classes (such as utility classes and libraries) the classes can be put in the path for the Common Classloader or an application-specific class loader rather than in an application or module. If you assemble a large, shared library into every module that uses it, the result is a huge file that takes too long to register with the server. In addition, several versions of the same class could exist in different classloaders, which is a waste of resources. For more information, see Chapter 2, Class Loaders, in Sun GlassFish Enterprise Server v3 Prelude Developer’s Guide.