Platform Development Studio - Developer’s Guide

Description of a Generated Project

The section describes a project generated from the Eclipse Wizard:

Generated project

Communication Service Project

Generating a Communication Service project the creates the directory structure illustrated in Listing 4-1.

The base directory is the directory given in the Eclipse Wizard input field Identifier. It contains the following files:

The directories and files in bold in Listing 4-1 are generated when building the common parts of the Communication Service; the others are generated by the Eclipse Wizard.

<Eclipse Project Name>

+- build.properties

+- common.xml

+- build.xml

+- <Identifier given in Ecplise Wizard>

|  +- dist //Generated by target dist in <Eclipse Project Name>/build.xml

|  |  +- <Package name>.store_<version.jar // Example store configuration

|  |  +- wlng_at_<Identifier>.ear //Deployable in access tier

|  |  +- wlng_nt_<Identifier>.ear //Deployable in network tier

|  +- common

|  |  +- build.xml //Build file for the common parts of the communication service

|  |  +- dist //Generated by target dist on 

             //<Eclipse Project Name>/common/build.xml

|  |  |  +- request_factory_skel //Skeletons for the RequestFactory,

                                 //one class for each service WSDL

|  |  |  +- tmp //Used during build. Contains classes, source, 

                //definitions, WSDLs, templates, and more.

|  |  |  +- <Identifier>.war // Web Service implementation

|  |  |  +- <Identifier>_callback.jar // Service callback EJB for 

                                      //the communication service

|  |  |  +- <Identifier>_callback_client.jar //Service call-back EJB used by 

                                           // the plug-in.

|  |  |  +- <Identifier>_service.jar // Service EJB 
                                      // for the communication service

|  |  +- resources // Contains application.xml and weblogic-application.xml

                   // for the access and network tier EAR files respectively.

                   // The files are packaged in the EAR files META-INF directory

|  |  +- src // Source directory for communication service common 

|  |  |  +- <Package name>/plugin

|  |  |  | +- <Web Services interface>PluginFactory // One per interface

                                                    // defined in the 

                                                   // Service WSDL files.

If the check-box Include WLNG Exceptions was checked when generating the Communication Service, the following exception definitions are added to the Web Service:

The exceptions are added only to the service facade, not to the plug-in to network interface.

If the exceptions listed above are present in the original WSDL they are reused; if not they are added.

Plug-in

When creating a plug-in for a given Communication Service, the directory structure illustrated in Listing 4-2 is created under the top-level directory. The base directory depends on the type of Communication Service the plug-in belongs to, such as, for example, px21_multimedia_messaging, or px21_sms. It also depends on whether the plug-in is for an existing Communication Service or for a new one.

If the plug-in is for an existing Communication Service, it is generated under one of the following directories:

If it is for a new Communication Service, the base directory is given in the Identifier entry field in the Eclipse Wizard.

The base directory contains the directory plugins, which contains subdirectories for each protocol that is being added. The names of the directories are the same as the name chosen for the Protocol field in the Eclipse Wizard.

Each of the sub-directories for a plug-in contains the following files:

Each plug-in sub-directory also contains the directories:

The directories and files in bold in Listing 4-2 are generated when building the plug-in, the others are generated by the Eclipse Wizard.

|  +- plugins // Container directory for all plug-ins for 

              // the communication service 

|  |  +- <Protocol> // One specific plug-in

|  |  |  +- build.xml // Build file for the plug-in 

|  |  |  +- build // Used during the build process

|  |  |  +- config // 

|  |  |  |  +- instance_factory 

|  |  |  |  |  +- instancemap //Instance map 

|  |  |  +- dist // Generated by target dist in build.xml for the plug-in

|  |  |  |  +- <Identifier>_<Protocol>_plugin.jar

|  |  |  |  +- <Package name>.store_<version>.jar

|  |  |  +- resources // Contains parts of weblogic-extension.xml

                      // for the network tier EAR file.

                     // the file is packaged in the EAR file’s META-INF directory

|  |  |  +- src

|  |  |  |  +- <Package name> // Directory structure reflecting 

                              // plug-in package name

|  |  |  |  |  +- management // Example MBean

|  |  |  |  |  |  +- MyTypeMBean.java

|  |  |  |  |  |  +- MyTypeMBeanImpl.java

|  |  |  |  |  +- <Web Services interface> // One per Service WSDL

|  |  |  |  |  |  +- north

|  |  |  |  |  |  |  +- <Web Services interface>PluginImpl.java 

                                 // Implmentation of the interface

|  |  |  |  |  +- <Type>PluginInstance.java

|  |  |  |  |  +- <Type>PluginService.java

                                // PluginService implementation

|  |  |  +- storage //Example of a store configuration.

|  |  |  |  +- wlng-cachestore-config-extensions.xml

SOAP2SOAP Plug-in

When creating a SOAP2SOAP plug-in, the directory structure described in Plug-in is created under the top-level directory. In addition, the directories and files in Listing 4-3 are generated. The directories and files in bold are created when building the plug-in; the others are generated by the Eclipse Wizard.

|  +- plugins // Container directory for all plug-ins for 

              // the communication service 

|  |  +- <Protocol> // One specific plug-in

|  |  |  +- build.xml // Build file for the plug-in 

|  |  |  +- build // Used during the build process

|  |  |  +- config // 

|  |  |  |  +- instance_factory 

|  |  |  |  |  +- instancemap //Instance map 

|  |  |  +- dist // Generated by target dist in build.xml for the plug-in

|  |  |  |  +- <Identifier>_<Protocol>_plugin.jar

|  |  |  |  +- <Package name>.store_<version>.jar //unused, empty

|  |  |  +- resources // Contains parts of weblogic-extension.xml

                      // for the network tier EAR file.

                     // the file is packaged in the EAR file’s META-INF directory

|  |  |  +- src

|  |  |  |  +- <Package name> // Directory structure reflecting 

                              // plug-in package name

|  |  |  |  |  +- client // Implementation of Web Service client

|  |  |  |  |  |  +- <Web Services interface>_Stub.java

|  |  |  |  |  |  +- <Web Services interface>.java

|  |  |  |  |  |  +- <Web Services interface>Service_Impl.java

|  |  |  |  |  |  +- <Web Services interface>Service.java

|  |  |  |  |  +- <Web Services call-back interface> // One per Call-back WSDL

|  |  |  |  |  |  +- south

|  |  |  |  |  |  |  +- <Web Services interface>PluginSouth.java 

                                 // Interface for network-triggered requests

|  |  |  |  |  |  |  +- <Web Services interface>PluginSouthImpl.java 

                                 // Implementation of the interface

|  |  |  |  |  +- <Web Services interface> // One per Service WSDL

|  |  |  |  |  |  +- north

|  |  |  |  |  |  |  +- <Web Services interface>PluginImpl.java 

                                 // Implementation of the interface

|  |  |  |  |  +- <Type>PluginInstance.java

|  |  |  |  |  +- <Type>PluginService.java

                                // PluginService implementation

|  |  |  |  |  +- schema // Java Representation of the schemas in the WSDLs

|  |  |  |  |  |  +- <Package name> // Directory structure reflecting 

                                   // namespace in WSDL

|  |  |  +- storage //Example of a store configuration. Empty.

|  |  |  +- wsdl // WSDLS and XML-to-Java mappings.

|  +- <Protocol Identifier_callback.war // Web Service implementation

                                        // for the SOAP2SOAP plug-in

As illustrated in Listing 4-3, a WAR file for the plug-in is generated. This WAR file contains the Web Service for network-triggered requests. It is only generated if there is a notification WSDL defined at generation-time. It will be packaged in the EAR for the Service Enabler.

Generated classes for a Plug-in

The generated classes are listed below.

Interface: ManagedPluginService

The interface a plug-in service needs to implement.

It extends the interfaces PluginService, PluginInstanceFactory and PluginServiceLifecycle.

Interface: PluginService

The interface that defines the plug-in service when it is registered in the Plug-in Manager.

Interface: PluginInstanceFactory

The factory that allows a plug-in service to create plug-in instances.

Interface: PluginServiceLifecycle

The interface that defines the lifecycle for a plug-in service. See States.

PluginService

Class.

Implements com.bea.wlcp.wlng.api.plugin.ManagedPluginService.

Defines the life-cycle for a plug-in service, see States.

Also holds the data that is specific for the plug-in instance.

The actual class name is <Communication Service Type>PluginService. This class manages the life-cycle for the plug-in service, including implementing the necessary interfaces that make the plug-in deployable in Network Gatekeeper. It is also responsible for registering the north interfaces with the Plug-in Manager. At startup time it uses the InstanceFactory to create one instance of each plug-in service and at activation time it registers these with the Plug-in Manager. The InstanceFactory uses an instancemap to find out which class it should instantiate for each plug-in interface implementation. The instance map is found under the resource directory.

ManagedPlugin Skeleton

The ManagedPlugin skeleton implements the following methods related to life-cycle management and should be adjusted for the plug-in:

In addition, this class defines which address schemes the plug-in can handle, in private static final String[] SUPPORTED_SCHEMES.

PluginInstance

Class.

Implements com.bea.wlcp.wlng.api.plugin.ManagedPluginInstance.

Defines the life-cycle for a plug-in instance, see States.

The actual class name is <Communication service Type>PluginInstance. This class manages the life-cycle for the plug-in instance including implementing the necessary interfaces that make the plug-in an instance in Network Gatekeeper.

It is also responsible for instantiating the classes that implement the traffic interfaces, and initializing stores to use and relevant MBeans.

See Interface: ManagedPluginInstance.

PluginNorth

This is an empty implementation of the Plug-in North interface. This interface is generated based on the WSDL files that define the application-facing interface. This is the starting point for the plug-in implementation.

The following files will be generated in the directory under src/...../<service name>/north:

PluginNorth skeleton

Below is an outline on what needs to be implemented in the plug-in skeleton.

The class contains a Java mapping of the methods defined in the Web Service. The methods are mapped one-to-one. The name of each method is the same as the name of the operation defined in the WSDL. The parameter is a class that mirrors the parameters in the input message in the Web Service request. The return type is a class that represents the output message in the Web Service Request.

RequestFactory Skeleton

The actual class name is <Communication service identifier>PluginFactory, such as, for example, NotificationManagerPluginFactory. This is a helper class used by the Service EJB. It serves two purposes:

The following files will be generated in the dist directory under request_factory_skel/src:

Generated classes for a SOAP2SOAP Plug-in

In addition to the generated classes for a regular plug-in, a SOAP2SOAP plug-in adds a few extra classes, because the network protocol is known.

Comparison with a Non-SOAP2SOAP Plug-in

The following generated code is similar to the code generated for the non-SOAP2SOAP plug-ins:

Client Stubs

These classes and interfaces are generated for each interface, based on the Service WSDLs:

<Web Services Interface>_Stub

Class.

Extends weblogic.wsee.jaxrpc.StubImp

Implements <Web Services Interface>

Used by the corresponding PluginNorth class.

<Web Services Interface>

Interface.

Extends java.rmi.Remote.

Implemented by <Web Services Interface>_Stub.

Defines the traffic methods.

<Web Services Interface>Service_Impl

Class.

Extends weblogic.wsee.jaxrpc.ServiceImpl.

Implements the Web Service.

<Web Services Interface>Service

Interface.

Extends javax.xml.rpc.Service.

Defines the traffic interfaces.

PluginInstance

In addition to the functionality in described in PluginInstance, in the PluginInstance generated for SOAP2SOAP plug-ins, the following occurs:

HTTPProxyManagement is described in section Managing and Configuring SOAP2SOAP Communication Services in Network Gatekeeper System Administrator’s Guide.

HeartbeatManagement is described in section Configuring Heartbeats in Network Gatekeeper System Administrator’s Guide.

PluginNorth

In addition to the functionality described in PluginNorth, this class:

PluginSouth

This class implements a Java representation of the Web Service implementation. It implements PluginSouth: see Interface: PluginSouth. When a network-triggered method is invoked, it:

RequestFactory

The RequestFactory for a SOAP2SOAP plug-in has the same functionality as described in RequestFactory Skeleton, but instead of serving as a skeleton, it is an implementation. It contains an implementation of createRequestInfo(...) which means that the Plug-in Manager does no routing based on destination address.

Build Files and Targets for a Communication Service Project

Main Build File

The main build file for the Communication Service contains the following targets:

Communication Service Common Build File

The build file for the common parts of the Communication Service contains the following targets:

Plug-in Build File

The build file for the plug-in contains the following targets:

Ant Tasks

The build files use a set of ant tasks and macros, described below:

The ant tasks are defined in $PDS_HOME/lib/wlng/ant-tasks.jar

cs_gen

This ant task builds the common parts of the Communication Service. Below is a description of the attributes.

Example:

<cs_gen destDir="${dist.dir}"

   packageName="com.bea.wlcp.wlng.example"

   name="say_hello"

   serviceType="example"

   company="BEA"

   version="4.0"

   contextPath="sayHello"

   soapAttachmentSupport="false"

   wlngHome="${wlng.home}"

   pdsHome="${pds.home}">

   <classpath refid="wls.classpath"/>

   <classpath refid="wlng.classpath"/>

   <servicewsdl file="${wsdl}/example_hello_say_service.wsdl"/>

</cs_gen>

plugin_gen

This ant task builds a plug-in for a Communication Service. Below is a description of the attributes.

Example:

<plugin_gen destDir="${dist.dir}"

   packageName="com.bea.wlcp.wlng.example.bla"

   name="say_hello"

   serviceType="example"

   esPackageName="com.bea.wlcp.wlng.example"

   protocol="bla"

   schemes=""

   company="BEA"

   version="4.0"

   pluginifjar="${dist.dir}/say_hello/common/dist/say_hello_service.jar">

   <classpath refid="wls.classpath"/>

   <classpath refid="wlng.classpath"/>

   <servicewsdl file="${wsdl}/example_hello_say_service.wsdl"/>

</plugin_gen>

cs_package

This ant task packages a Communication Service. Below is a description of the attributes.

Example:

<cs_package destfile="${cs.dist}/${enabler.ear.name}.ear"

   duplicate ="fail"

   displayname="${enabler.ear.name}">

   <descriptorfileset dir="${csc.dir}/resources/enabler/META-INF"

    includes="*.xml"/>

  <descriptorfileset dir="${cs.name}/plugins"

    includes="*/resources/META-INF/*.xml"/>

   <manifest>

      <attribute name="Bundle-Name" 

         value="${enabler.ear.name}"/>

      <attribute name="Bundle-Version"

         value="${manifest.bundle.version}"/>

      <attribute name="Bundle-Vendor"

         value="${manifest.bundle.vendor}"/>

      <attribute name="Weblogic-Application-Version"

         value="${manifest.bundle.version}"/>

   </manifest>

   <fileset dir="${csc.dist}">

      <include name="*_service.jar"/>

   </fileset>

   <zipfileset dir="${cs.stage}">

      <include name="*plugin.jar"/>

   </zipfileset>

</cs_package>

javadoc2annotation

This ant macro annotates an MBean interface based on the JavaDoc. The macro is defined in the common.xml build file for the

The annotations are rendered as descriptive information by the Gatekeeper Administration console. Below is a description of the attributes.

Example:

<javadoc2annotation

   tempDir="${plugin.generated.dir}/mbean_gen_tmpdir"

   destDir="${plugin.classes.dir}"

   sourceDir="${plugin.src.dir}"

   classpath="javadoc.classpath">

</javadoc2annotation>