S2Axis Basic Usage

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

Table of Content

• Web Application Configuration
• Server Configuration
• Client Configuration
• Server/Client Common Configuration

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 s2axis-1.0.1.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:

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:

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 s2axis-1.0.1.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.