Figure 5 shows the structure of a JAR file for server packages.

Figure 5. JAR File for Server Packages

The root of the JAR file contains the WASP-INF directory, which in turn contains the classes, lib and wsdl subdirectories. The classes directory stores class files. The lib directory stores JAR files used by deployed services. WSDL files are placed in the wsdl directory. (WSDL files describe Web services. You can use our tool Java2WSDL to generate them.) WASP-INF also contains the deployment descriptor for the package: package.xml. For more information about deployment descriptors, please see Deployment Descriptors.

As you can see, there is no wasp.xml file in the JAR file. This is because this file is generated automatically from a package's deployment descriptor during deployment.

Package JAR files can be built with the following tools:

When you deploy a package, you may specify a context in addition to the name and targetNamespace from the deployment descriptor. The service is deployed to target_server_url/context/{targetNamespace}name. The context provides more information for the package scope. Contexts are represented by subdirectories of the application directory. The default is the root context. They can have recursively nested subdirectories, called subcontexts. Contexts can be specified when deploying either with the command-line tool or the administration console GUI.

The context name is added to the path of the service. For example, if you deploy the HelloService on http://localhost:6060 to the helloContext context, the service will then be accessible from the path http://localhost:6060/helloContext/{tns}HelloService. If you do not specify any context during deployment, the package will be deployed to the root context, in this case http://localhost:6060/{tns}HelloService.

There is a special context for system packages: the system context. The system context behaves similarly to other contexts. However, there are special handling requirements for the service path of the packages from this context. The context name is not added to the path of the services. The services will therefore be accessible from the path as if they were deployed to the default (root) context.

There are some restrictions for deploying packages to a context. A package can be installed to a given context when:

	Note
	Two packages are considered to be the same if they have the same package name and targetNamespace.

There are restrictions on deploying packages that depend on another package. Packages dependent on another package can be installed to the same context or to its subcontext(s).

Context names must not start or end with a slash (/). They may not contain the characters .., :, *, ?, ", <, >, | or ~.

See also Service Contexts.

Packages may be deployed with one of the following tool kits:

	Note
	If you want to deploy a package that depends on another package, you have to deploy the independent package first.

When the server starts, it scans the application directory and obtains information about all installed packages. If an error occurs with an installed package, for instance, because it cannot be registered or loaded, an error message including a stack trace is printed on the console. If hot deployment is enabled, the server will try to deploy the package periodically and the error message will be shown repeatedly until the package is repaired, undeployed or removed from the application directory.

When there are packages dependent on the problematic package, they will probably not be deployed.

You can use our WaspPackager tool to create a client package JAR file: see Figure 7:

Figure 7. JAR file for Client Packages

As with a server package, client packages have a package.xml file in the WASP-INF directory. Other files, such as classes and some resources, are in the JAR file root. For example, if you want to use XSLTInterceptor for the client side, place the style sheets in.xls and out.xsl in the root of the package's JAR file.

You can use our WaspPackager tool to create a ready-to-deploy client JAR file:

WaspPackager --client --package HelloPackage --output hello.jar --deployment-descriptor package.xml
            --classpath classes

More information about WaspPackager and its switches can be found in Deploy Tool.

You can also use the JDK JAR Tool to create JAR files. To learn how to use this tool, see the JDK documentation.

The client-side application directory works as a cache. Every package that has been used before is cached here.

When the client starts, it scans the classpath and finds out if the cache for the package exists. (this means the directory for the package is in the application directory). If the cache for the package does not exist, a new directory is created, the deployment descriptor is unpacked there and a configuration file is generated. If the cache for the package exists in the application directory, the cached deployment descriptor and configuration is used.

To test for the existence of a cache, a client compares the package's name, target namespace and version. If you update a deployment descriptor in the JAR file of a package that has already been cached, you must first delete the directory for that package from the application directory, to make the changed version accessible.

You can globally turn off usage of cache with the attribute useCache="false" on the packageRepository module in clientconf.xml; in this case an application directory is not created on the filesystem and deployment descriptors are read directly from the package's JAR file.

A client deployment descriptor is slightly different from the server version. The first difference is that you should set the client-package attribute:

<package name="InterceptorService"
                    client-package="true" ... > ... </package>

The next difference between a client and a server deployment descriptor is the Web service specification. In the service-client element, you can define the:

For more about deployment descriptors, see Deployment Descriptors.

Client packages can be configured with either a service URL or a port name, as an attribute of the <service-client> element. Only one of these attributes should be defined in the <service-client> element.

It is also possible to configure a client package with neither service URL nor service type defined. This configuration is reusable for several client applications. See Default Client Package for an example and more details.

In Example 69, the attribute port-name contains the QName of the port type.

<package name="InterceptorService" ...
          xmlns:tns="http://systinet.com/package/demo/advanced/interceptor/server" ... > 
    ... 
    <service-client port-name="svc:InterceptorService" ... /> 
    ... 
</package>

In Example 70, the attribute url contains the URL of the service's endpoint.

<package name="InterceptorService" ... > 
    <service-client url="http://localhost:6060/demo/advanced/InterceptorService" .../> 
    ... 
</package>

Other elements and their attributes, such as dependency, are used similarly to the corresponding elements in server packages. It is important to note that, if a package depends on another package, the dependent package must be on the classpath.

In Example 71, we look at an example of a deployment descriptor in which a custom interceptor is used on the client side:

<?xml version="1.0" encoding="UTF-8"?>
<package client-package="true" name="InterceptorService"
  targetNamespace="http://wso2.com/package/demo/advanced/interceptor/server"
    version="1.0" xmlns="http://wso2.com/wasp/package/1.2"
    xmlns:tns="http://wso2.com/package/demo/advanced/interceptor/server" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <license>http://wso2.com</license>
    <processing name="InterceptorProcessing">
        <interceptor direction="in out"
            implementation-class="demo.advanced.interceptor.MyInterceptor" 
            name="MyInterceptor"/>
    </processing>
    <service-client port-name="svc:InterceptorService"
        processing="tns:InterceptorProcessing" 
        xmlns:svc="http://wso2.com/wsdl/example/interceptor/"/>
</package>

A client package can be deployed on a server as well. In this case, all classes from the package are packed into a JAR file and added to the lib directory in the package structure. The client package on a server can be useful for another service that works as a client and looks up a service which needs a client configuration. It can also work as a library package.

You can reuse a custom configuration for several client applications. Simply write the client package deployment descriptor without either a service URL or port name defined. In this case a default client package is generated. This client package is then used for each client that includes it on its classpath, without caching in app_classpath.

Note that if a client classpath includes a package with URL or port-name specified and a package without this information, the package that specifies the service URL or port has priority.

The deployment descriptor in Example 72, from the MessageFormat custom serialization demo, results in a default client package being generated. This can be used to configure a number of client applications with custom serialization without having to write a deployment descriptor for each one. Compare to the non-reusable deployment descriptor in Example 71.

<?xml version="1.0" encoding="UTF-8"?>
<package client-package="true" name="MessageFormatSerializers"
targetNamespace="http://wso2.com/package/demo/advanced/messageformat/client"
    version="4.6.1" xmlns="http://wso2.com/wasp/package/1.2"
    xmlns:mf="http://wso2.com/demo/advanced/messageformat"
    xmlns:tns="http://wso2.com/package/demo/advanced/messageformat/client"
    xmlns:wasp="http://wso2.com/wasp/app/builtin_serialization">
    <dependency ref="wasp:builtin_serialization" version="1.0"/>
    <processing name="MessageFormatProcessing">
        <use ref="wasp:EncodedSerialization"/>
        <schema location="MessageFormat.xsd" 
            namespaceURI="http://wso2.com/demo/advanced/messageformat"/>
        <type-mapping name="MessageFormatMapping">
            <type maps-to="java.text.MessageFormat" name="mf:MessageFormat"/>
        </type-mapping>
        <serialization
        deserializer-class="demo.advanced.messageformat.MessageFormatDeserializer"
        following-parts="wasp:ReflectionSerializer"
        name="MessageFormatSerialization"
        preceding-parts="wasp:BasicConstructSerializer"
        serialized-type="mf:MessageFormat" 
        serializer-class="demo.advanced.messageformat.MessageFormatSerializer"/>
    </processing>
    <export push="false">
        <use ref="tns:MessageFormatProcessing"/>
    </export>
</package>

The deployment descriptor of the library package should set the library attribute, as shown in Example 13.

<package name="LibraryPackageService"
        library="true"
        targetNamespace="http://systinet.com/package/demo/advanced/library/server"
        ...> 
    ... 
</package>

A package that needs to use the library package must create a dependency on this package in its deployment descriptor. Example 74 shows how.

<package
                    name="LibraryPackageUserService" ...
                    xmlns:tns="http://systinet.com/package/demo/advanced/library/server" ...
                    > <dependency ref="tns:LibraryPackageService"
                    version="1.0"/> ... </package>

For more information about dependencies see Deployment Descriptors.

A package can share Java classes and libraries from a number of library packages.