Seasar DI Container with AOP

This is a document for S2Axis-V1.0.0. Documents for older versions of S2Axis are included in their respective distribution archive file.

Table of Content

Abstract

S2Axis allows components defined in dicon file to be made available as a web service and also allows web service to be used as a component.

When Axis is used directly, instance management of web service implementation class is often done by Axis. This is usually sufficient for a small project but for large business application projects, it is usually more efficient to use DI (Dependecy Injection) and AOP (Aspect Oriented Programming) with controls transactions.-

By using S2Axis, components may be developed using full features of DI and AOP offered by S2, and then be deployed by Axis which than may be released as web services.

Setup

Requirements

S2Axis requires S2, S2Remoting, and Axis. Following versions are currently supported:

S2Axis S2 S2Remoting Axis
1.0.0 2.1.3 and later 0.0.7 and later 1.2
1.0.0-RC2 2.1.3 and later 0.0.7 and later 1.2
1.0.0-RC1 2.1.3 and later 0.0.7 and later 1.2
1.0.0-alpha5 2.1.3 and later 0.0.7 and later 1.2RC3
1.0.0-alpha4 2.1.3 and later 0.0.7 and later 1.2RC2

Not all combinations of versions have been tested. Following combination of versions have been tested:

Environment

S2Axis requires the following software:

  • Sun JDK (J2SE SDK) 1.4 or later. S2Axis-V1.0.0 is developed using JDK 1.4.2_08. Sun JDK may be downloaded from here.
  • S2 version 2.1.3 or later is required. (When using J2SE5.0 or later, S2.2 or later is required.) S2Axis-V1.0.0 is developed and tested with S2.2.9. It may be downloaded from here.
  • S2Remoting version 0.0.7 or later. S2Axis-V1.0.0 is developed and tested with S2Remoting-V1.0.0. It may be downloaded from here.
  • Axis version 1.2 or later is required. S2Axis-V1.0.0 is developed and tested with Axis 1.2 (Axis ver1.2 is included with S2Axis). It may be downloaded from here.
  • Web container supporting Servlet2.3 or later is required. S2Axis-V1.0.0 is developed and tested with Tomcat 5.0.30. It may be downloaded from here.

Development Environment

Similar to other S2 software, S2Axis is distributed as archived Eclipse Java project.

  • Eclipse3.0 or later is required. S2Axis-V1.0.0 is developed and tested with Eclipse3.0.2. It may be downloaded from here.
  • S2 version 2.1.3 or later is required. (When using J2SE5.0 or later, S2.2 or later is required.) S2Axis-V1.0.0 is developed and tested with はS2.2.9. It may be downloaded from here. After downloading the file, import it to Eclipse workspace.
  • S2Remoting version 0.0.7 or later is required. S2Axis-V1.0.0 is developed and tested with S2Remoting 1.0.0. It may be downloaded from here. After downloading the file, import it to Eclipse workspace.

S2AxisExamples archive file is distributed as an Eclipse Tomcat project with Sysdeo Tomcat plugin.

  • Sysdeo Tomcat plugin is required. S2AxisExamples-V1.0.0 is developed and tested with Sysdeo Tomcat plugin V3. It may be downloaded from here.

Download

S2Axis and S2AxisExamples may be downloaded from here.

Installation

S2Axis

  • After downloading S2Axis-V1.0.0.zip file, extract the content to some directory.
  • If the files were extracted to Eclipse's workspace directory, rename directorys2-axis-1.0.0 to s2-axis.
  • Execute Eclipse and select [File]-[Import] from the menu.
  • From [Import] wizard, select [Existing Projects into Workspace] and then select the [Next>] button.
  • Select [Select root directory] radio button and then select the [Browse] button to the right of it. Browse through directories to the s2-axis-1.0.0 directory (or to s2-axis if the directory has been renamed) where the archive files where extracted. Select the [OK] button to select this directory.
  • Select the [Finish] button to import from this directory.

S2AxisExamples

  • Extract files in the S2AxisExamples-V1.0.0.zip archive file to a directory.
  • If the files were extracted to Eclipse's workspace directory, rename directory s2-axis-examples-1.0.0 to s2-axis-examples.
  • Execute Eclipse and select [File]-[Import] from the menu.
  • From [Import] wizard, select [Existing Projects into Workspace] and then select the [Next>] button.
  • Select [Select root directory] radio button and then select the [Browse] button to the right of it. Browse through directories to the s2-axis-examples-1.0.0 directory (or to s2-axis-examples if the directory has been renamed) where the archive files where extracted. Select the [OK] button to select this directory.
  • Select the [Finish] button to import from this directory.

Running the Sample Program

To verify that software were properly installed, run the sample program.

  • Right click the s2-axis-examples project and select [Tomcat Project]-[Update context definition].
  • If a dialog box appears stating context was successfully updated, select the [OK] button.
  • Select [Tomcat]-[Start Tomcat] from the menu.
  • Check to be sure the following message appears in the console view "Info: Server startup in 99999 ms".
  • Open a web browser (such as Mozilla Firefox) and open the URI:
http://localhost:8080/s2-axis-examples/services
  • If a page similar to the following appears, S2Axis example was successfully installed.

If there is an error, there may be some error in web container settings.

Basic Usage

Web Application Configuration

To use S2Axis, it is necessary to set Axis and S2 in web.xml configuration file. Refer to Axis and S2 references on detailed setting instructions.
S2Axis registers components into Axis during S2 initialization. So, Axis must be initialized before S2. Thus, set Axis's servlet load-on-startup to be smaller than S2.

Below is the content of web.xml file included with S2AxisExample. In this example, Axis's load-on-startup to 10 and S2's load-on-startup is set to 20.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  "http://java.sun.com/dtd/web-app_2_3.dtd"
>
<web-app>
  <display-name>S2AxisExamples</display-name>

  <filter>
    <filter-name>s2filter</filter-name>
    <filter-class>
      org.seasar.framework.container.filter.S2ContainerFilter
    </filter-class>
  </filter>

  <filter-mapping>
    <filter-name>s2filter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

  <listener>
    <listener-class>
      org.apache.axis.transport.http.AxisHTTPSessionListener
    </listener-class>
  </listener>

  <servlet>
    <servlet-name>AxisServlet</servlet-name>
    <display-name>Apache-Axis Servlet</display-name>
    <servlet-class>
      org.apache.axis.transport.http.AxisServlet
    </servlet-class>
    <load-on-startup>10</load-on-startup>
  </servlet>

  <servlet>
    <servlet-name>AdminServlet</servlet-name>
    <display-name>Axis Admin Servlet</display-name>
    <servlet-class>
        org.apache.axis.transport.http.AdminServlet
    </servlet-class>
    <load-on-startup>10</load-on-startup>
  </servlet>

  <servlet>
    <servlet-name>SOAPMonitorService</servlet-name>
    <display-name>SOAPMonitorService</display-name>
    <servlet-class>
        org.apache.axis.monitor.SOAPMonitorService
    </servlet-class>
    <init-param>
      <param-name>SOAPMonitorPort</param-name>
      <param-value>5001</param-value>
    </init-param>
    <load-on-startup>10</load-on-startup>
  </servlet>

  <servlet>
    <servlet-name>s2servlet</servlet-name>
    <display-name>s2servlet</display-name>
    <servlet-class>
      org.seasar.framework.container.servlet.S2ContainerServlet
    </servlet-class>
    <init-param>
      <param-name>configPath</param-name>
      <param-value>app.dicon</param-value>
    </init-param>
    <init-param>
      <param-name>debug</param-name>
      <param-value>false</param-value>
    </init-param>
    <load-on-startup>20</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/servlet/AxisServlet</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
    <servlet-name>AxisServlet</servlet-name>
    <url-pattern>/services/*</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
    <servlet-name>SOAPMonitorService</servlet-name>
    <url-pattern>/SOAPMonitor</url-pattern>
  </servlet-mapping>

  <!-- uncomment this if you want the admin servlet -->
  <!--
  <servlet-mapping>
    <servlet-name>AdminServlet</servlet-name>
    <url-pattern>/servlet/AdminServlet</url-pattern>
  </servlet-mapping>
  -->

  <servlet-mapping>
    <servlet-name>s2servlet</servlet-name>
    <url-pattern>/s2servlet</url-pattern>
  </servlet-mapping>

  <session-config>
    <!-- Default to 5 minute session timeouts -->
    <session-timeout>5</session-timeout>
  </session-config>

  <!-- currently the W3C havent settled on a media type for WSDL;
    http://www.w3.org/TR/2003/WD-wsdl12-20030303/#ietf-draft
    for now we go with the basic 'it's XML' response -->
  <mime-mapping>
    <extension>wsdl</extension>
    <mime-type>text/xml</mime-type>
  </mime-mapping>

  <mime-mapping>
    <extension>xsd</extension>
    <mime-type>text/xml</mime-type>
  </mime-mapping>

  <welcome-file-list id="WelcomeFileList">
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
</web-app>

Server Configuration

Including s2-axis.dicon File

Server software using S2Axis should include s2-axis.dicon file in app.dicon file.

<components>
    <include path="s2-axis.dicon"/>
    ・・・
</components>

s2-axis.dicon is included in s2-axis-1.0.0.jar so location does not have to be specified.

Deploying Service

To deploy a component as web service, specify <meta> element as a child to the component's <component> element.

    <component name="Echo" class="org.seasar.remoting.axis.examples.ex01.EchoImpl">
        <meta name="axis-service"/>
    </component>

Except when WSDD file is specified in <meta> element (explained later), name attribute is necessary in <component>element. URI of released service is as follows:

When namespace is not specified in a dicon file
context-path/services/name
When namespace is specified in a dicon file
context-path/services/namespace/name

Service Definition

Several setting may be done by setting org.seasar.remoting.axis.server.ServiceDef within <meta> element.

    <component name="Hello" class="org.seasar.remoting.axis.examples.ex02.HelloImpl">
        <meta name="axis-service">
            <component class="org.seasar.remoting.axis.server.ServiceDef">
                <property name="serviceType">
                    @org.seasar.remoting.axis.examples.ex02.Hello@class
                </property>
            </component>
        </meta>

        <property name="..."> ... </property>
    </component>

org.seasar.remoting.axis.server.ServiceDef has the following properties:

Property Description
serviceType Type of service to be release. By specifying specific interface type, unecessary method will not be released.
allowMethods Method name to be released. When several methods are to be released, separate method name with spaces.
provider Type of service provider. Currently, only RPC and Msg are supported. Defaults to RPC when not specified.

Refer to Quick Reference section on org.seasar.remoting.axis.ServiceDef for details.

Mapping Definition

When Axis is used and argument type and return type of a service is application specific JavaBeans, whose type are not directly supported by JAX-JPC, values to be passed to these types must be Serializer / Deserializer. Unless specific Serializer / Deserializer is necessary, it is not necessary to specify one because S2Axis uses automatic type mapping provided by Axis.
In those situations when it is necessary to specify Serializer / Deserializer or when it is necessary to specify set a Java package to XML namespace, type mapping mapping must be registered.
Several type mapping may be registered in ServiceDef.

    <component name="Hello" class="org.seasar.remoting.axis.examples.ex02.HelloImpl">
        <meta name="axis-service">
            <component class="org.seasar.remoting.axis.server.ServiceDef">
                <initMethod name="addTypeMapping">
                    <arg>
                        <component type="org.seasar.remoting.axis.server.TypeMappingDef">
                            <property name="...">・・・</property>
                        </component>
                    </arg>
                </initMethod>
            </component>
        </meta>

        <property name="..."> ...</property>
    </component>

org.seasar.remoting.axis.server.TypeMappingDef has the following properties:

Property Description
type Java type class. This property must be specified.
namespaceURI Namespace URI of XML type. If omitted, defaults to URI from Java type package.
namespacePrefix Namespace prefix of XML type. If omitted, defaults to default namespace.
localPart Local name of XML type. If omitted, defaults to Java type class.
serializer Serializer. If omitted, defaults to Axis BeanSerialzierFactory.
deserializer Deserializer. If omitted, defaults to Axis BeanDeserialzierFactory.
encodingStyle Encoding style. If omitted, defaults to encoded.

Refer to Quick Reference section on org.seasar.remoting.axis.TypeMappingDef for details.

WSDD Service Properties

When Web service has a WSDL and Java implementation class was generated by using Axis's WSDL2Java, web service may be deployed by specifying deploy.wsdd generated by WSDL2Java.

    <component name="Magazine"
      class="org.seasar.remoting.axis.examples.ex05.MagazineSoapBindingImpl">
      <meta name="axis-service">
        "org/seasar/remoting/axis/examples/ex05/deploy.wsdd"
      </meta>
      ...
    </component>

In this situation, because Java type and XML type mapping, which are specified when executing WSDL2Java, are included in deploy.wsdd all necessary type mapping are deployed.
It is possible to include one service definition (<service> element) in WSDD. Deployment fails when there are several service definitions.

Client Configuration

S2Axis allows web services to be used as a component.

Dynamic Call

To call service through Java interface, write dicon file as follows:

    <!-- Web service proxy -->
    <component name="Echo" class="org.seasar.remoting.axis.examples.ex01.Echo">
        <aspect>remoting</aspect>
    </component>

    <!-- Remote call interceptor -->
    <component name="remoting"
      class="org.seasar.remoting.common.interceptor.RemotingInterceptor"/>

    <!-- Axis connector -->
    <component name="connector"
      class="org.seasar.remoting.axis.connector.AxisConnector">
        <property name="baseURL">
            "http://localhost:8080/s2-axis-examples/services/"
        </property>
    </component>

    <!-- Axis service -->
    <component class="org.apache.axis.client.Service" autoBinding="none"/>

Proxy is necessary for each web service. Specify Java interface of web service in class attribute of <component> element. In this component, specify RemotingInterceptor as an aspcet. Proxy must have one <component> definition for each web service interface.

RemotingInterceptor intercepts calls to proxy methods, and redirect the call to Axis connector. In the above sample, RemoteInterceptor property is set to Axis connector by S2's remote binding. RemotingInterceptor must have one <component> definition for each Axis connector.

Axis connector calls a web service through Axis service. In the above sample, Axis connector property is set to Axis service by S2's automatic binding. baseURL property is set to base URI of web service endpoint. In the actual communication, value specified in the name attribute of proxy's <component> element is appended to this base URI. Axis connector must have one <component> definition for each web service endpoint.

Axis service uses SOAP protocol to communicate with other web services. Axis service requires at lease one <component> definition for each S2 container.

Static Call

To call a service using stub generated by WSDL, create a dicon file as follows:

    <component class="org.seasar.axis.examples.ex05.Magazine">
        locator.getMagazine()
    </component>

    <component name="locator"
      class="org.seasar.axis.examples.ex05.MagazineServiceLocator"/>

Service locator is the class generated by WSDL2Java. Stub with implementation of service's Java interface may be retrieved by the getXxx() method of this class.

Client/Server Common Configuration

s2-axis.diconFile Include

When the following features are to be used, s2-axis.dicon file must be included in app.dicon file at both server and client.

<components>
    <include path="s2-axis.dicon"/>
    ・・・
</components>

s2-axis.dicon does not have to be concerned about location because it is included in s2-axis-1.0.0.jar.

Handler Properties

Beside services, S2 instance may manage handlers.

    <component name="fooRequestHandler"
      class="org.seasar.remoting.axis.examples.ex06.LoggingHandler">
        <meta name="axis-handler"/>

        ...
    </component>

name attribute must be specified in a <component>. In handler chain definition, a handler may be referenced by this name.

Deploying WSDD

Arbitrary WSDD file may be deployed by S2Axis.

<components>
    <meta name="axis-deploy">"org/seasar/remoting/axis/examples/ex07/deploy.wsdd"</meta>
</components>

This is the same as deploying using Axis AdminClient, but S2Axis deploys when S2 is initialized.

Specifying Axis Engine

Service, handler, and Axis engine that is to be used to deploy WSDD file may be specified in a dicon file.

<components>
    <meta name="axis-engine">"default-client"</meta>
</components>

Axis engine is determined by the content of <meta> element.
Refer to section "Content that can be specified in service-engine" in the the quick reference.

Samples

S2Axis-Examples demostrates most basic features supported by S2Axis. Source is divided into server side and client side sources. Client source is created as JUnit (S2Unit) test case. Source codes files are in the following directories:

Server side
org.seasar.axis.examples.exnn package in src/server directory
Client side
org.seasar.axis.examples.exnn package in src/client directory

ex01 Releasing a Component as a Web Service

Sample to release a simple web service

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
        <component name="Echo" class="org.seasar.remoting.axis.examples.ex01.EchoImpl">
                <meta name="axis-service"/>
        </component>
</components>

Client side is call dynamically.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <component name="remoting"
      class="org.seasar.remoting.common.interceptor.RemotingInterceptor"/>

    <component class="org.apache.axis.client.Service"/>

    <component name="connector"
      class="org.seasar.remoting.axis.connector.AxisConnector">
        <property name="baseURL">
            "http://localhost:8080/s2-axis-examples/services/"
        </property>
    </component>

    <component class="org.seasar.remoting.axis.examples.ex01.Echo">
        <aspect>remoting</aspect>
    </component>
</components>

ex02 Releasing Specific Interface

When implementation class is released, unnecessary methods may also become released. For example, interfaces that were not implemented or when several interfaces are implemented. In ex02, implemented class HelloImpl implements two interfaces, but setMessage(String) method in MessageSettable is not released as a web service.
In this situation, Java interface to become available is made public. (If only one interface is implemented or if all implemented interfaces are to be released, it is not necessary to specify as in this sample.)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <component name="Hello"
        class="org.seasar.remoting.axis.examples.ex02.HelloImpl">
        <meta name="axis-service">
            <component class="org.seasar.remoting.axis.server.ServiceDef">
                <property name="serviceType">
                    @org.seasar.remoting.axis.examples.ex02.Hello@class
                </property>
            </component>
        </meta>
        <property name="message">"Hello"</property>
    </component>
</components>
Comment out <property> element and restart the web container. WSDL for Hello should contain にsetServiceType(String) method.

ex03 Using Automatic Type Mapping

In this sample, argument and return value data type of a service is a JavaBean. Nevertheless, type mapping are done automatically at both client side and server side.

ex04 Using Session Scope

Axis has a proprietary session scope service that uses HTTP session. When session scope service is used in S2Axis, service life cycle management is doen by S2.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
        <component name="Counter" class="org.seasar.axis.examples.ex04.CounterImpl"
            instance="session"
        >
                <meta name="axis-service"/>
        </component>
</components>

This sample will not properly work if value of instance attribute is changed tosingleton or prototype (client will error.)

When session scope is to be used, session tracking must be made effective at the client.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <component name="remoting"
      class="org.seasar.remoting.common.interceptor.RemotingInterceptor"/>

    <component class="org.apache.axis.client.Service">
        <property name="maintainSession">true</property>
    </component>

    <component name="connector"
      class="org.seasar.remoting.axis.connector.AxisConnector">
        <property name="baseURL">
            "http://localhost:8080/s2-axis-examples/services/"
        </property>
    </component>

    <component class="org.seasar.remoting.axis.examples.ex04.Counter">
        <aspect>remoting</aspect>
    </component>
</components>

The sample will not work properly if value of maintainSession attribute is set to false.

ex05 Using WSDL

This is a sample created using WSDL2Java to generated Java stubs and a skelton. WSDD file generated by WSDL2Java is specified.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <component name="Magazine"
      class="org.seasar.remoting.axis.examples.ex05.MagazineSoapBindingImpl">
        <meta name="axis-service">
            "org/seasar/remoting/axis/examples/ex05/deploy.wsdd"
        </meta>

        <property name="title">"CanCam"</property>
        <initMethod name="addModel">
            <arg>
                <component
                  class="org.seasar.remoting.axis.examples.ex05.Model">
                    <property name="name">"Yuri Ebihara"</property>
                    <property name="age">25</property>
                </component>
            </arg>
        </initMethod>
        <initMethod name="addModel">
            <arg>
                <component
                  class="org.seasar.remoting.axis.examples.ex05.Model">
                    <property name="name">"Naoko Tokuzawa"</property>
                    <property name="age">20</property>
                </component>
            </arg>
        </initMethod>
        <initMethod name="addModel">
            <arg>
                <component
                  class="org.seasar.remoting.axis.examples.ex05.Model">
                    <property name="name">"Asami Usuda"</property>
                    <property name="age">20</property>
                </component>
            </arg>
        </initMethod>
    </component>
</components>

On the client side, static stub generated from WSDL is called.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
        <component name="locator" 
                class="org.seasar.remoting.axis.examples.ex05.MagazineServiceLocator"
        />

        <component class="org.seasar.remoting.axis.examples.ex05.Magazine">
                <!-- locator.getMagazine() -->
                locator.getMagazine(
                    new java.net.URL(locator.getMagazineAddress() + 
                        locator.getMagazineWSDDServiceName()))
        </component>
</components>

ex06 Using S2 To Manage Handler Instance

This sample, handler instance managed by S2 is used in service request chain and response chain.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <component name="Foo"
      class="org.seasar.remoting.axis.examples.ex06.FooSoapBindingImpl">
        <meta name="axis-service">
            "org/seasar/remoting/axis/examples/ex06/deploy.wsdd"
        </meta>
    </component>

    <component name="fooRequestHandler"
      class="org.seasar.remoting.axis.examples.ex06.LoggingHandler">
        <meta name="axis-handler"/>

        <property name="message">"Enter Foo"</property>
    </component>

    <component name="fooResponseHandler"
      class="org.seasar.remoting.axis.examples.ex06.LoggingHandler">
        <meta name="axis-handler"/>

        <property name="message">"Exit Foo"</property>
    </component>
</components>

To use this handler, request flow and response flow are inserted into WSDD generated by WSDL2Java.

<!-- Use this file to deploy some handlers/chains and services      -->
<!-- Two ways to do this:                                           -->
<!--   java org.apache.axis.client.AdminClient deploy.wsdd          -->
<!--      after the axis server is running                          -->
<!-- or                                                             -->
<!--   java org.apache.axis.utils.Admin client|server deploy.wsdd   -->
<!--      from the same directory that the Axis engine runs         -->

<deployment
    xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

  <!-- Services from FooService WSDL service -->

  <service name="Foo" provider="java:RPC" style="rpc" use="encoded">
      <parameter name="wsdlTargetNamespace"
        value="http://ex06.examples.axis.remoting.seasar.org"/>
      <parameter name="wsdlServiceElement" value="FooService"/>
      <parameter name="wsdlServicePort" value="Foo"/>
      <parameter name="className"
        value="org.seasar.remoting.axis.examples.ex06.FooSoapBindingImpl"/>
      <parameter name="wsdlPortType" value="Foo"/>
      <operation name="ping" qname="operNS:ping"
          xmlns:operNS="http://ex06.examples.axis.remoting.seasar.org" soapAction=""
      >
      </operation>
      <parameter name="allowedMethods" value="ping"/>

      <requestFlow>
          <handler type="fooRequestHandler"/>
      </requestFlow>
      <responseFlow>
          <handler type="fooResponseHandler"/>
      </responseFlow>
  </service>
</deployment>

When client software is executed, following message is displayed at the server.

[DEBUG] http-8080-Processor24 org.seasar.remoting.axis.examples.ex06.LoggingHandler
    Enter Foo
[DEBUG] http-8080-Processor24 org.seasar.remoting.axis.examples.ex06.LoggingHandler
    Exit Foo

ex07 Deploying WSDD with S2Axis

In this sample, EchoHandler, which comes as a sample in Axis, will be added in WSDD as a provider service and then deployed.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
        <meta name="axis-deploy
            ">"org/seasar/remoting/axis/examples/ex07/deploy.wsdd"
        </meta>
</components>

The difference between ex05 is <components> element is used instead of <component>.
WSDD that is deployed is as follows:

<deployment
    xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">

    <service name="EchoHandler" provider="Handler" style="rpc" use="encoded">
        <parameter name="handlerClass" value="org.apache.axis.handlers.EchoHandler"/>
    </service>
</deployment>

S2 and S2Axis do not manage EchoHandler instance written in WSDD. They only take part in deployment.

ex08 Deploying Handler and WSDD at Client

In this sample, handler and WSDD file specified in dicon file will be deployed.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//SEASAR2.1//DTD S2Container//EN"
        "http://www.seasar.org/dtd/components21.dtd">
<components>
    <include path="s2-axis.dicon"/>

    <component name="remoting"
      class="org.seasar.remoting.common.interceptor.RemotingInterceptor"/>

    <component class="org.apache.axis.client.Service"/>

    <component name="connector"
      class="org.seasar.remoting.axis.connector.AxisConnector">
        <property name="baseURL">
            "http://localhost:8080/s2-axis-examples/services/"
        </property>
    </component>

    <component class="org.seasar.remoting.axis.examples.ex01.Echo">
        <aspect>remoting</aspect>
    </component>

    <component name="countHandler" 
            class="org.seasar.remoting.axis.examples.ex08.CountHandler">
        <meta name="axis-handler"/>
    </component>

    <meta name="axis-deploy">
      "org/seasar/remoting/axis/examples/ex08/deploy.wsdd"
    </meta>
</components>

Deployed WSDD is as follows:

<deployment
    xmlns="http://xml.apache.org/axis/wsdd/"
    xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
    <globalConfiguration>
         <requestFlow>
             <handler type="countHandler"/>
         </requestFlow>
         <responseFlow>
             <handler type="countHandler"/>
         </responseFlow>
     </globalConfiguration>
</deployment>

Management of countHandler instance specified in WSDD is done by S2.

Quick Reference

dicon file

s2-axis.dicon

dicon file used by S2Axis. It is included in s2-axis-1.0.0.jar file so it can be included without specifying the location.
It is required at the server side.
At the client side, it is only necessary if handler or WSDD is to be deployed.

<meta> Element

Content of <components> element

Name C S Content Description
axis-deploy yes yes String Deploy WSDD file, which has a content specified path string, to Axis. Path name of WSDD file is specified as a relatvie path from the class path.
Instance management of service and handler that have been specified in WSDD file are done by Axis. S2 and S2 do not management them.
Service and handler, which have been deployed by S2Axis, may be referenced from within WSDD file.
axis-engine yes yes String Specify method to get Axis engine that will deploy services, handlers, and WSDD.
Refer to "Method to Get Axis Engine" for details.

Content of <component> Element

Property C S Content Description
axis-handler yes yes Empty Deploy as a handler a component written as a new element.
axis-service no yes empty Deploy component, which was written in a parent element, as a Axis service.
When component implements an interface defined in a method, that method will be released. If an interface is not implemented, public methods that have not been defined as java.lang.Object is released.
ServiceDef type component Deploy components that has been written in a parent element as Axis service.
Refer to ServiceDef for detailds.
String Deploy components that has been written in a parent element as Axis service.
Details of a service is as specified in <service> element in the WSDD file, which has been specified by the string path of the content. WSDD file path is specified by relative path from the class path.

Component

org.seasar.remoting.axis.ServiceDef

Components that are used on the server is set in the <meta> element.
It is used to specified which components are to be released as a service.

Properties

Property Type Description
serviceType String Specify type of service that are to be released. Unnecessary method may be avoided from being released by specifying an interface type.
Defaults to component type. However, if a component has only one method definition that has an implemented interface, type of that interface is used.
allowMethods boolean Name of method to release. To release several methods, separate method names with a space.
If omitted, defaults as follows:
1.When serviceType is specied.
All public methods with specified type will be release. However, method with java.lang.Object type will not be released.
2.When service has a method with an implemented interface
All methods defined in the interface will be released.
3.When a service does not have an implemented interface
All public will be released. However, method with java.lang.Object type will not be released.
provider String Type of service provider.
Currently, only RPC and Msg are supported. Defaults to RPC when omitted.

Method

Method Description
addTypeMapping(TypeMapping) Register type mapping. Refer to the next section for detail on TypeMapping.

org.seasar.remoting.axis.TypeMappingDef

Components used at the server, set to ServiceDef component.
Used to specify detailed type mapping of components to be released as a service.

Property Type Description
type Class Java type class. It propery is required.
namespaceURI String XML type namespace URI. Defaults to URI from Java type package.
namespacePrefix String XML type namespace prefix. Defaults to default namespace.
localPart String XML type local name. Defaults to Java type class name.
serializer Class Serializer. Defaults to Axis BeanSerialzierFactory.
deserializer String Deserializer. Defaults to Axis BeanDeserialzierFactory.
encodingStyle String Encoding style. Defaults to encoded.

org.seasar.remoting.axis.connector.AxisConnector

Used to dynamically connect to a web service from a component used at a client.

Properties

Property Type Description
baseURL String Base URI of service to connect.
This URI concatenated with proxy component name (value of name attribute in <component> element), which is an aspect of S2Remoting's RemotingInterceptor, is actually used to connect to a service.

org.seasar.remoting.common.interceptor.RemotingInterceptor

Component offering S2Remoting.
To use a component as a web service at the client, this component is used as an aspect.

org.apache.axis.client.Service

Component offered by Axis.
Required when dynamic call is used at a client.

Miscellaneous

Service name released

When WSDD is specified
Value of name attribute in <service> element specified in WSDD is used.
context-path/services/name
When namespace is not specified in a dicon file
Value of のname attribute in <component> element in dicon file is used.
context-path/services/name
When namespace of dicon file is specified
Value of namespace attribute in <components> element and value of name attribute in <component> element in dicon file is used.
context-path/services/namespace/name

service-engine Settings

Content Description
(Others) Same as setting "default"
"default" If S2 container is set javax.servlet.ServletContext then same as "default-server", if not then same as setting "default-client".
"default-client" Retrieve component implemenation set by javax.xml.rpc.Service from S2 container and use that engine.
"default-server" To try find engine from searching servlet:AxisServlet. If it could not find one, try to find an engine by searching servlet:AxisEngine.
"s2:name" Use component as Axis engine retrieved from S2 container name.
"servlet:name" Use attribute as Axis engine retrieved from ServletContext's name.
(Other) Use component retrieved by string specified from S2 container string as Axis engine.
Trans. by H.OzawaCopyright© 2004-2005, The Seasar Foundation and the others. All rights reserved.