Using Persistent Deployment

Overview ^Locate

Before a Web service can be exposed on the server, its files must be uploaded to the server. The server must also be configured to allow client access. This process is called deployment of the Web service. All the Web service-related files are held in the package and the configuration information is written in the deployment descriptor.

WSO2 SOA Enablement Server contains a number of useful features for deployment. The first feature is that the deployment is remote. This means that there is no need for local access to the machine on which WSO2 SOA Enablement Server is running. The second feature is that uploading is done via SOAP. This means that all WSO2 SOA Enablement Server's features related to SOAP are available to deployment as well. The third feature is security. An administrator can easily forbid deployment and grant or revoke a user's rights to deploy.

Deployment is accessible through the deployment tools, which are included in the Core-Tools component (see the Components chapter).

The following sections describe the deployment of a simple Web service that has only one class and the deployment of a package that has several classes. Undeployment scenarios describe basic undeployment of packages from the server. For deployment without prior undeployment you can use redeployment, which simplifies the process for developers during the development cycle.

Single Class Deploymenthello.jar ^Locate

If you have only one class and want to deploy it, you do not have to write deployment descriptors or a package for it. You can simply use our Deploy tool, as follows for the HelloService class:

Deploy --target http://localhost:6060 --class demo.basic.hello.server.HelloService 
                 --uri /HelloService

For a detailed description of Undeploy, refer to Deployment Tools.

Complex Deployment Scenarios ^Locate

A service package is a JAR file which contains all the information about the service. Deploying service packages is referred to as complex deployment. You need to create a service package for your Web service in any of the following cases:

Your Web service contains more than one class.
It contains any libraries or custom WSDLs.
It needs a special configuration.

Once you have created a service package, you only need to distribute it. Note that the deployment parameters (for example, the service path) are recorded in the JAR file. This makes the deployment command simpler. The package can also be easily deployed to the server from your web browser using the Package Management features of the Administration Console.

'Create Everything for Me' Scenario ^Locate

The following command shows the easiest way to create a ready-to-deploy JAR file, using our WaspPackager tool and the HelloPackage:

WaspPackager --package HelloPackage --output hello.jar --service-name HelloService
                --uri /HelloService --class demo.basic.hello.server.HelloService --classpath classes

In this example, we told WaspPackager to create a service package named HelloPackage. The output file is hello.jar, the name of the service is HelloService and it should be published on URI /HelloService. The implementation class is demo.basic.hello.server.HelloService and can be found in the classes directory. This directory is very important because WaspPackager will take it and put it into a package in its entirety. If your service needs other resources, placing them in the classpath directory will include them in your service.

Now you can use Deploy to deploy the package to the server:

Deploy --target http://localhost:6060 hello.jar

With Your Own WSDL File ^Locate

If you have your own WSDL file, the WaspPackager can add it to the package being created, through the --wsdl-file and --wsdl-service parameters. Here we demonstrate this with the HelloPackage and the pre-existing HelloService.wsdl:

WaspPackager --package HelloPackage --output hello.jar --service-name HelloService
            --uri /HelloService --class demo.basic.hello.server.HelloService --wsdl-file HelloService.wsdl
            --classpath classes

Then you can use Deploy to deploy the package to the server, as in the "Create Everything For Me" scenario.

With Your Own Deployment Descriptor ^Locate

If you have written your own deployment descriptor, WaspPackager can use it when creating the package through the --dd parameter. The whole deployment configuration is contained in the deployment descriptor, as with the helloServiceDD.xml:

WaspPackager --package HelloPackage --output hello.jar --dd helloServiceDD.xml
            --classpath classes

Then you can use Deploy to deploy the package to the server, as in the "Create Everything For Me" scenario.

Service In Disabled State ^Locate

Sometimes, additional security settings must be added to a deployed service before the first call. In this case, Deploy offers the possibility of disabling all the services immediately following the Deploy process, preventing calls until the services are enabled, through the --disabled parameter:

Deploy --target http://localhost:6060 hello.jar --disabled

Deploying Dependent Packages ^Locate

When dependencies occur between your packages, you must deploy the independent packages (roots) first.

Undeployment Scenarios ^Locate

Undeploying a Package by Name ^Locate

If you know the name of the package to undeploy , you can Undeploy with the --package parameter:

Undeploy --target http://localhost:6060 --package http://my.org:HelloService

Undeploying a Package by its JAR File Name ^Locate

If you have the JAR file of the package to undeploy, you can use Undeploy as follows:

Undeploy --target http://localhost:6060 hello.jar

Undeploying Dependent Packages ^Locate

When there are packages dependent on the package you're trying to undeploy, undeployment will not succeed unless you first undeploy all dependents or set the --force parameter to true:

Undeploy --target http://localhost:6060 --force hello.jar

	Note
	Be careful when you undeploy with "force." Undeploying a package will cause errors if another package still depends on it.

Redeployment Scenarios ^Locate

Redeployment is the process of deployment without prior undeployment. Redeployment can save time during the development cycle. You need to deploy a package only once, and when you make some changes in the Web services related files, simply use redeployment to make the Web service files accessible. If the package hasn't been deployed yet, the redeployment will work like deployment and fully Deploy the Web services.

Single Class Redeployment ^Locate

Single Class Redeployment works in a similar fashion to Single Class Deployment. If you have only one class and want to redeploy it, use our Deploy Tool as follows, with the --redeploy parameter:

Deploy --redeploy --target http://localhost:6060 --class demo.basic.hello.server.HelloService
            --uri /HelloService

Redeployment of a Package Jar File ^Locate

If you have a package's JAR file which you made using the WaspPackager Tool, you can redeploy it by including the jar in the --target parameter:

Deploy --redeploy --target http://localhost:6060 hello.jar

Redeployment of Dependent Packages ^Locate

As with Undeployment, when there are packages dependent on the package you're trying to redeploy, redeployment will not succeed unless you first Undeploy all dependents or set the force parameter to true:

Deploy --redeploy --target http://localhost:6060 --force hello.jar

'Hot' Deployment ^Locate

Hot deployment is a method for quickly deploying a package on a running server. Users of application servers are likely to be familiar with this. It saves development time because not only is it faster than remote tool-based deployment, but you do not need to stop and restart the server every time you want to test an alteration to a package, when you prefer to work directly in a file system.

	Caution
	By default, hot deployment is enabled. However, we recommend using it only for testing or evaluation. Using hot deployment in a production environment is not recommended as it may decrease performance. See the hot deployment configuration section for instructions on disabling hot deployment..

In hot deployment, the server periodically scans the application directory for changes. The server checks for the creation of new deployment packages, as well as changes to or the deletion of existing packages. This may occur with either a packed or unpacked package. (For more information about packages see the Packages chapter.) We envision the following use cases:

Hot deployment of a packed package (package JAR file):
- Deploying a package by copying the package JAR file to the application directory
- Undeploying a package by deleting the package JAR file from the application directory
- Redeploying a package by the copying a new version of the package's JAR file to the application directory
Hot deployment of an unpacked package (package directory):
- Deploying a package by copying the entire package directory to the application directory
- Undeploying a package by deleting the package directory from the application directory
- Redeploying a package by copying new versions of arbitrary files into the package directory (such as deployment descriptor, classes, libraries, WSDLs, resources, etc.) and changing the timestamp of the package.xml file.

	Note
	The hot deployment feature works only with persistent deployment, not with runtime publishing. For example, if a service is runtime published, copying a new version of the service implementation class onto the class path does not refresh a previously published service.

Hot Deployment of a Packed Package ^Locate

Hot deployment at the package JAR file level can be useful when you have a script that builds WSO2 SOA Enablement Server packages. In this case you can add to the script a command for copying the output JAR file into the application directory. When the server detects a new package in the application directory, it deploys it.

To redeploy a package, copy the new version of the package JAR file over the existing file in the application directory. The WSO2 SOA Enablement Server will first undeploy the old version of the package and then deploy the new one.

To undeploy a package, delete the package JAR file from the application directory. When the WSO2 SOA Enablement Server detects that the JAR file is gone, it undeploys it.

For more information about how to create WSO2 SOA Enablement Server package JAR files, see the "Create Everything For Me" scenario or the WSO2 SOA Enablement Server Packager tool documentation.

WSO2 SOA Enablement Server considers files with the suffix ".jar" to be packed packages. Thus you can temporarily undeploy a package by changing the suffix of the file (for example, changing hello.jar → hello.jar.tmp) and redeploy the package by changing the suffix back to .jar.

Hot Deployment of an Unpacked Directory ^Locate

Hot deployment at the level of an unpacked package's directory is useful for partially updating a package (such as the services' implementation classes) in connection with an IDE. IDEs are set up to compile classes directly into the WASP-INF/classes subdirectory of a given package directory.

To deploy an unpacked package, copy the entire package directory to the application directory. WSO2 SOA Enablement Server detects the occurrence of new unpacked packages and deploys them. To prepare the package, you can use the WaspPackager tool and the resulting JAR file will be unpacked to the appropriate package directory inside the application directory. You can also create a package directory manually, but you must keep the required structure. The structure of a package in the application directory is described in the Server Package section of the Packages chapter.

When you want to redeploy an unpacked package, copy the updated files over the existing files in the package directory (for example classes to WASP-INF/classes, WSDLs toWASP-INF/wsdl etc.) and change the timestamp of the deployment descriptor file, WASP-INF/package.xml. The WSO2 SOA Enablement Server periodically checks the timestamp of this file. When it sees that the timestamp has changed, it redeploys the package.

To undeploy an unpacked package, delete the package directory from the application directory. When WSO2 SOA Enablement Server sees that the WASP-INF/package.xml of a given package has disappeared, it undeploys that package. As with packed packages, you can undeploy a package by changing the suffix of its package.xml file. In the latter case, all package files stay in the file system.

Configuring Hot Deployment ^Locate

Through the Administration Console, you can:

Globally enable/disable hot deployment
Set up the scan period (time period in millisecond between scans of the application directory)

Both of these properties can be configured in the Administration Console from the section Server Preferences Hot Deployment. See Setting Hot Deployment. Hot deployment has a default scan period of 5000 ms.

Programmatically, you can enable/disable hot deployment:

For any context (a context is a directory inside the application directory)
For any package (either unpacked or packed)

The following XML snippet shows the default configuration of hot deployment, which is contained in the deployment descriptor of the hot deployment component (system/hot_deploy.jar). The name attribute corresponds to the name either of the context directory, the directory of the unpacked package or the package JAR file.

<module name="HotDeployer"
        xmls:conf= …>
    <conf:enable>true</conf:enable>
    <conf:scanPeriod>5000</conf:scanPeriod>
    <conf:context name="" enable="true"/>
    <conf:context name="system" enable="false"/>
</module>

In the configuration above:

Hot deployment is enabled
Scan period is 5000 ms
The root context (context with name="") is enabled - all its subcontexts and packages will be scanned unless specified otherwise.
The system context is disabled - none of its subcontexts or packages will be scanned

Alternatively, you could configure hot deployment so that only a particular package or context will be scanned. Consider the following configuration of hot deployment:

<module name="HotDeployer"
        xmls:conf= …>
    <conf:enable>true</conf:enable>
    <conf:scanPeriod>5000</conf:scanPeriod>
    <conf:context name="" enable="false"/>
    <conf:context name="myContext" enable="true"/>
    <conf:context name="HelloDemo.jar " enable="true"/>
</module>

In this configuration:

The root context is disabled - none of its subcontexts and packages will be scanned unless specified otherwise.
The MyContext context is enabled - all its subcontexts and packages will be scanned unless specified otherwise.
The HelloDemo.jar package is enabled for scanning.

To change the configuration from the default settings, you have to update the configuration in the deployment descriptor in the hot_deploy.jar file and restart the server.