1_2/xdocs/faq.html

<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>Axis2 FAQ</title>
  <link href="css/axis-docs.css" rel="stylesheet" type="text/css" media="all">
</head>

<body lang="en">
<h1>Frequently Asked Questions on Apache Axis2</h1>

<p>Got a question to be answered on Axis2? Then this document is just what
the doctor ordered.</p>

<h2>Ask your Questions Here</h2>

<p>If you have any other doubts/issues, e-mail your questions to:</p>
<ul>
  <li>Developers - :<a
    href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></li>
  <li>Users - :<a
    href="mailto:axis-user@ws.apache.org">axis-user@ws.apache.org</a></li>
</ul>

<p>Prefix subject with [Axis2]. <a
href="http://ws.apache.org/axis2/mail-lists.html">Subscribe</a> to our
mailing lists.<a href="http://ws.apache.org/axis2/mail-lists.html"></a></p>

<h2>Content of Questions and Answers</h2>
<ul>
  <li>General
    <ul>
      <li><a href="#a1">I'm having a problem using Axis2. What should I
        do?</a></li>
      <!--li><a href="#a2">What is OMElement, What does it represent?</a></li-->
      <li><a href="#a3">Integration security tests fail with JDK 1.5</a></li>
      <li><a href="#a4">Axis2 is not working with Java 6</a></li>
    </ul>
  </li>
  <li>Class Loading Issues
    <ul>
      <li><a href="#b1">How do I access resources in my service /module
        archive file?</a></li>
    </ul>
  </li>
  <li>Client API
    <ul>
      <li><a href="#c1">I want to do Request Response Messaging, Where should
        I look?<br>
        </a></li>
      <li><a href="#c2">I want to do One Way Messaging, Where should I
        look?</a></li>
      <li><a href="#c3">Error: 'to do two Transport Channels the Addressing
        Modules must be engaged'</a></li>
      <li><a href="#c4">I have engaged addressing, and when I try to invoke a
        service I get an exception</a></li>
      <li><a href="#c5">What is Axis Repository?</a></li>
    </ul>
  </li>
  <li>Maven
    <ul>
      <li><a href="#d1">Error when trying to run maven on Axis2</a></li>
      <li><a href="#d2">I have problems building with maven 1.1</a></li>
      <li><a href="#d3">What versions of maven are supported?</a></li>
      <li><a href="#d4">What are the frequently used maven commands?</a></li>
    </ul>
  </li>
  <li>Services
    <ul>
      <li><a href="#e1">How do I have multiple services in one service
        archive?</a></li>
    </ul>
  </li>
  <li>Web Archive/ Server Side
    <ul>
      <li><a href="#f1">I see an internal server error page when I try to
        view the WSDL file.<br>
        </a></li>
    </ul>
  </li>
  <li>WSDL and Code Generation
    <ul>
      <li><a href="#g1">Given a WSDL 2.0 document with HTTP Binding to
        WSDL2Java, should it not be able to generate a client stub</a></li>
    </ul>
  </li>
</ul>

<h2>General</h2>
<ol>
  <li><a name="a1"></a><strong>I'm having a problem using Axis2. What should
    I do?</strong><br>

    <p>First make sure you go through the user guide and this FAQ. If you are
    using a released version of Axis2, then there is a possibility that your
    problem has already being fixed in the latest code. <a
    href="http://ws.zones.apache.org/dist/axis2/nightly/">Download Axis2
    nightly builds</a> and test again.</p>
    <p>If the problem still persists, then try to search for your question in
    our <a
    href="http://marc.theaimsgroup.com/?l=axis-dev&amp;r=1&amp;w=2">developer</a>
    or <a
    href="http://marc.theaimsgroup.com/?l=axis-user&amp;r=1&amp;w=2">user</a>
    mailing archives as it might have already being answered.</p>
    <p>If your problem is not answered in the mailing list, now is the best
    time to post your question to the axis-user mailing list. If you think it
    is a bug, please fill a bug report in <a
    href="http://issues.apache.org/jira/browse/AXIS2">JIRA</a>. Please attach
    all the supportive information, like your wsdl, schema, clients,
    services, stacktraces, etc., to the JIRA issue you created, as it will
    help one of our contributors to re-create the problem. <b>PLEASE DO NOT
    ASK QUESTIONS USING JIRA; USE IT ONLY AS AN ISSUE TRACKER.</b></p>
    <p>If you are asking for an explanation of a feature in Axis2, there is a
    possibility that there is an article or FAQ written on it. Please search
    the web as there are lots of articles written and hosted by various
    sources on the web.</p>
    <p><b>Note</b> : When you ask questions in the mailing list, please
    remember that everyone working in our project are volunteers. No-one can
    be forced to fix your bugs (See <a
    href="http://www.apache.org/foundation/faq.html#what-is-apache-NOT-about">What
    is Apache not about?</a> ).</p>
    <p>Make sure you add enough information about your problem with
    stacktraces and any other supportive information. It will improve the
    chances of your question being answered. Prefixing your mail subject with
    prefixes like "URGENT" will not help you in any means. Yes we also accept
    all the blames about Axis2 in these mailing lists, as those will
    definitely help us to improve Axis2 :) .</p>
  </li>
  <li><a name="a3"></a><strong>Integration security tests fail with JDK
    1.5</strong><br>

    <p>You have to add Bouncy Castle as a JCE provider. Add the following
    entry to java.security file of the appropriate JRE on your machine. This
    file is available in the lib\security\ directory within the JRE
    directory.</p>
    <p>security.provider.7=org.bouncycastle.jce.provider.BouncyCastleProvider</p>
    <p>security.provider.# will have to be decided depending on the existing
    entries in the java.security file</p>
    <p>NOTE: For Windows XP, the correct version can be found using 'java
    -version'. The correct file is JRE (typically c:\Program
    Files\Java\jre&lt;version&gt;\lib\security\java.security.</p>
  </li>
  <li><a name="a4"></a><strong>Axis2 is not working with Java 6</strong><br>

    <p>You have to copy the stax-api jar in the Axis2 distribution into your
    JRE's endorsed directory (see info on endorsed directory here -<a
    href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">
    http://java.sun.com/j2se/1.4.2/docs/guide/standards/</a>).</p>
    <p>This issue can also be resolved by copying the stax-api jar to
    Tomcat's common/endorsed folder, when deploying Axis2 in Tomcat.</p>
  </li>
</ol>

<h2>Class Loading Issues</h2>
<ol>
  <li><a name="b1"></a><strong>How do I access resources that I put into my
    service /module archive file?</strong></li>

  <p>Axis2 has the notion of service isolation where each service or module
  gets its own class loader. Using this class loader you can access any
  resource that you put into your service archive file. You may want to
  access your resources from different locations. For example,</p>

  <p>1. A third party module wants to access your resources. Then the
  scenario is as follows:</p>
  <pre>   AxisService myService =
   messageContext.getAxisConfiguration().getAxisService("serviceName"); </pre>

  <p>or</p>
  <pre>   AxisService myService = msgCtx.getAxisService();</pre>

  <p>Then you can use the service class loader through which you can access
  its resources</p>
  <pre>   ClassLoader clsLoader = myService.getServiceClassLoader();
   clsLoader.getResourceAsStream("myResource");</pre>

  <p>2. To initialize the service implementation class at the MessageReceiver
  level, the following steps need to be taken</p>
  <pre>   AxisService service = msgCtx.getAxisService();
   ClassLoader clsLoader = service.getServiceClassLoader();
   Class.forName("serviceName",clsLoader,true);</pre>

  <p>NOTE : Axis2 default MessageReciver uses the same technique to
  initialize service implementations</p>

  <p>3. If you want to load your resources at the service implementation
  class, then the scenario is as follows</p>
  <pre>   getClass().getClassLoader().getResourceAsStream("myResource");</pre>
</ol>

<h2>Client API</h2>
<ol>
  <li><a name="c1"></a><strong>I want to do Request-Response Messaging, Where
    should I look?</strong><br>

    <p>Look at the <a
    href="https://svn.apache.org/repos/asf/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/ServiceClient.java"
    target="_blank">ServiceClient</a> class, for more information please read
    the <a href="@axis2_version_dir@/adv-userguide.html" target="_blank">User's Guide</a></p>
  </li>
  <li><a name="c2"></a><strong>I want to do One Way Messaging, Where should I
    look?</strong><br>

    <p>From Axis2 0.94 onwards, both request-response and one way messaging
    will be handled by <a
    href="https://svn.apache.org/repos/asf/webservices/axis2/trunk/java/modules/core/src/org/apache/axis2/client/ServiceClient.java"
    target="_blank">ServiceClient</a>.</p>
  </li>
  <li><a></a><strong>When I try to do a non blocking call with
    </strong>useSeparateListener=true
    <p>I get the error <i>to do two Transport Channels the Addressing Modules
    must be engaged</i>, Why is this?<br>
    </p>
    <p>To do the two transport channel invocation, you need to engage the
    addressing module. You can enable it by un-commenting the entry in the
    axis2.xml file or Call.engageModule(QName). However, addressing is
    enabled by default.</p>
  </li>
  <li><a name="c4"></a><strong>I have engaged addressing, and when I try to
    invoke a service I get an exception </strong><br>

    <p>If you have engaged addressing, then you must have wsa:action, the
    required WS-Addressing header. You have to call <br>
    <code>option.setAction("urn:myaction");</code>. Note that the action
    should be a URI.</p>
  </li>
  <li><a name="c5"></a><strong>What is Axis2 Repository?</strong><br>

    <p>The Repository stores the configuration of Axis2. The users should
    specify the repository folder of the Axis Server (HTTP or TCP). In the
    case of Tomcat, it is the webapps/axis2/WEB-INF folder. The following
    picture shows a sample repository.</p>
    <img src="images/faq/1.jpg">
    <p>Modules and services have an archive format defined and they are
    automatically picked up by Axis2 when they are copied to corresponding
    folders.</p>
  </li>
</ol>

<h2>Maven</h2>
<ol>
  <li><a name="d1"></a><strong>I just installed Maven and it gives an error
    when I try to run Maven on Axis2.</strong>
    <p>Axis2 requires itest plugin to run some of the tests. Better get it
    using the following command.</p>
    <ul>
      <li>maven plugin:download -DgroupId=maven-itest-plugin
        -DartifactId=maven-itest-plugin -Dversion=1.0
        -Dmaven.repo.remote=http://ws.zones.apache.org/~dims/maven</li>
    </ul>
  </li>
  <li><p><a name="d2"></a><strong>I have problems building with Maven
    1.1</strong></p>
    <p>It seems that Maven 1.1 doesn't come bundled with the required
    artifact plugin. Run the following command to get it updated<br>
    </p>
    <ul>
      <li>maven plugin:download -DgroupId=maven
        -DartifactId=maven-artifact-plugin -Dversion=1.6</li>
      <p>You may also need to update the itest plugin, using the above
      command in 1.</p>
    </ul>
  </li>
  <li><p><a name="d3"></a><strong>What versions of Maven are
    supported?</strong></p>
    <p>Versions 1.0.2 and 1.1 are supported. Maven2 is not supported as
    yet.</p>
  </li>
  <li><a name="d4"></a><strong>What are the frequently used Maven
    commands?</strong></li>

  <p></p>

  <table border="1" align="center">
    <tbody>
      <tr>
        <th scope="col">
          <div align="left">
          Command</div>
        </th>
        <th scope="col">
          <div align="left">
          Description</div>
        </th>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven</div>
        </td>
        <td>
          <div align="left">
          Downloads relevant jars if not available, and compiles and runs the
          tests in the system.</div>
        </td>
      </tr>
      <tr>
        <td>maven clean</td>
        <td>Cleans all the content built so far in the target folder. This
          will not clean the jar repository.</td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven test</div>
        </td>
        <td>
          <div align="left">
          Runs only the tests. Performs automatic compilation of changed
          sources as well. This will not run SOAP interop tests</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven clean all-tests</div>
        </td>
        <td>
          <div align="left">
          Cleans up and runs all offline and online tests.</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven itest</div>
        </td>
        <td>
          <div align="left">
          To run the online-mode tests for say the modules/integration, run
          "maven itest" from modules/integration</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven test itest</div>
        </td>
        <td>
          <div align="left">
          To run all the tests for say the modules/integration, run "maven
          test itest" from modules/integration</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven -g</div>
        </td>
        <td>
          <div align="left">
          Lists all the commands available in Maven</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven multiproject</div>
        </td>
        <td>
          <div align="left">
          Generates the site.</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven idea:multiproject</div>
        </td>
        <td>
          <div align="left">
          Generates IDEA .ipr, .iml and .iws project files.</div>
        </td>
      </tr>
      <tr>
        <td>
          <div align="left">
          maven -Dmaven.test.skip=true</div>
        </td>
        <td>Builds Axis2 and skips all the tests.</td>
      </tr>
      <tr>
        <td>maven dist-min-bin</td>
        <td>Generates the binary version of Axis2 minimal distribution</td>
      </tr>
      <tr>
        <td>maven dist-min-src</td>
        <td>Generates the source version of Axis2 minimal distribution</td>
      </tr>
      <tr>
        <td>maven dist-std-bin</td>
        <td>Generates the binary version of Axis2 standard distribution</td>
      </tr>
      <tr>
        <td>maven dist-std-src</td>
        <td>Generates the source version of Axis2 standard distribution</td>
      </tr>
      <tr>
        <td>maven release</td>
        <td>Generates all the distributables for Axis2.</td>
      </tr>
      <tr>
        <td>maven clean jar -Dmaven.test.skip=true -o</td>
        <td>Cleans the content in the target folder and compiles your source,
          without running the tests or downloading snapshots of the
          dependancies. This is the quickest way of compiling Axis2 sources.
          However it is highly recommended to run the tests all the time.</td>
      </tr>
    </tbody>
  </table>
  <br>
</ol>

<h2>Services</h2>
<ol>
  <li><a name="e1"></a><strong>How do I have multiple services in one service
    archive?</strong></li>

  <p>It's just a matter of writing a services.xml file to configure the
  service or services in an archive file. The corresponding services.xml
  <strong>must</strong> look as follows,</p>
  <pre>   &lt;serviceGroup&gt;
   &lt;service <strong>name="myService1"</strong>&gt;
   ...........................
   &lt;/service&gt;

   &lt;service <strong>name="myService2"</strong>&gt;
   ...........................
   &lt;/service&gt;
   &lt;serviceGroup&gt;</pre>

  <p>NOTE : The name attribute is a compulsory attribute that will become the
  name of the services. If you want to have one service in the archive file,
  then there are two options. You can either have one service inside the
  serviceGroup tag or have only one service tag, as shown below, in your
  services.xml, in which case, the name of the service will be the name of
  the archive file, which you cannot override.</p>
  <pre>   &lt;service&gt;
   ...............
   &lt;service&gt;</pre>
</ol>

<h2>Web Archive / Server side</h2>
<ol>
  <li><a name="f1"></a><strong>I see an internal server error page when I try
    to view the WSDL file.</strong><br>

    <p>This happens specifically with Tomcat 4.x and 5.0 in a JDK 1.5
    environment. The reason is that the system picks up a wrong transformer
    factory class. This can be solved simply by putting the <a
    href="http://www.apache.org/dist/java-repository/xalan/jars/">xalan-2.7.0.jar</a>
    into the axis2/WEB-INF/lib directory</p>
  </li>
</ol>

<h2>WSDL and Code Generation</h2>
<ol>
  <li><a name="g1"></a><strong>Given a WSDL 2.0 document with HTTP Binding to
    WSDL2Java, should it not be able to generate a client stub similar to
    what happens given a WSDL 1.1 document with SOAP Binding?</strong></li>

  <p>WSDL 2.0 is not supported yet. We do not have a working WSDL 2.0
  reader.</p>

  <p>However the codegen engine works off WOM (not WSDL4J). Hence if the WSDL
  2.0 reader is done, we are all set to generate code for it.</p>

  <p>And yes, it is perfectly possible for the codegen to generate code for
  the HTTP binding. We already have the client API support for making the
  REST calls and it should be a matter of putting in a correct template.</p>
</ol>
</body>
</html>