Author: veithen
Date: Sun Oct 7 18:57:39 2012
New Revision: 1395361
URL: http://svn.apache.org/viewvc?rev=1395361&view=rev
Log:
Migrated client-side-axis from the old Forrest sources.
Added:
axis/axis1/java/trunk/src/site/xdoc/client-side-axis.xml
- copied, changed from r1395359,
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/client-side-axis.xml
Copied: axis/axis1/java/trunk/src/site/xdoc/client-side-axis.xml (from
r1395359,
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/client-side-axis.xml)
URL:
http://svn.apache.org/viewvc/axis/axis1/java/trunk/src/site/xdoc/client-side-axis.xml?p2=axis/axis1/java/trunk/src/site/xdoc/client-side-axis.xml&p1=webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/client-side-axis.xml&r1=1395359&r2=1395361&rev=1395361&view=diff
==============================================================================
---
webservices/axis/trunk/site/src/java/src/documentation/content/xdocs/java/client-side-axis.xml
(original)
+++ axis/axis1/java/trunk/src/site/xdoc/client-side-axis.xml Sun Oct 7
18:57:39 2012
@@ -1,45 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN"
"./dtd/document-v12.dtd">
-<document>
- <header>
- <title>WebServices - Axis</title>
- </header>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+<document xmlns="http://maven.apache.org/XDOC/2.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
+ <properties>
+ <title>Client-Side Axis</title>
+ </properties>
<body>
-<a name="Client-SideAxis"/>
-<section>
-<title>Client-Side Axis</title>
-
-<a name="TableOfContents"/>
-<section>
-<title>Table of Contents</title>
+<section name="Table of Contents">
-<ul>
- <li><a href="#Introduction">Introduction</a></li>
- <li><a href="#CoreTCPIPConcepts">Core TCP/IP Concepts</a></li>
- <li><a href="#CoreHTTPConcepts">Core HTTP Concepts</a></li>
- <li><a href="#JAX-RPC">JAX-RPC</a></li>
- <li><a href="#Testing">Testing</a></li>
- <li><a href="#ConfiguringClient-sideHandlers">Configuring Client-side
handlers</a></li>
- <li><a href="#Redistribution">Redistribution</a></li>
- <li><a href="#DynamicallyDiscoveringAndBindingToAWebService">Dynamically
Discovering and Binding to a Web Service</a></li>
- <li><a href="#CallConfiguration">Call configuration</a></li>
- <ul>
- <li><a href="#StandardProperties">Standard Properties</a></li>
- <li><a href="#AxisProperties">Axis Properties</a></li>
- </ul>
- <li><a href="#NetworkConfiguration">Network configuration</a></li>
- <li><a href="#TroubleshootingNetworkProblems">Troubleshooting Network
Problems</a></li>
- <ul>
- <li><a href="#WhatCanTheDeveloperOfAWebServiceClientApplicationDo">What
can the developer of a Web Service client application do?</a></li>
- </ul>
-</ul>
+<macro name="toc"/>
</section>
-<a name="Introduction"/>
-<section>
-<title>Introduction</title>
+<section name="Introduction">
<p>This document looks at the issues related to developing the client side of
a Web Service using Axis.</p>
@@ -47,9 +39,7 @@
</section>
-<a name="CoreTCPIPConcepts"/>
-<section>
-<title>Core TCP/IP Concepts</title>
+<section name="Core TCP/IP Concepts">
<p>We are not going to explain TCP/IP in any detail, as it is far too complex.
Some of the concepts and features of the technology are worth covering.</p>
@@ -76,11 +66,9 @@
</section>
-<a name="CoreHTTPConcepts"/>
-<section>
-<title>Core HTTP Concepts</title>
+<section name="Core HTTP Concepts">
-<p>HTTP is at its heart, a very simple protocol. The client opens a TCP
connection to a port on the remote system, usually port number 80. It then
issues an HTTP request – a verb such as GET, POST, PUT or other standard
request, a URL relative to the server and an HTTP version string. The client
then sends zero or more headers – name:value pairs on individual lines,
and then a blank line marking the end of headers. Those requests which involve
data upload -such as POST- then continue with the upload of the data. Then the
client waits for the server to respond.</p>
+<p>HTTP is at its heart, a very simple protocol. The client opens a TCP
connection to a port on the remote system, usually port number 80. It then
issues an HTTP request – a verb such as GET, POST, PUT or other standard
request, a URL relative to the server and an HTTP version string. The client
then sends zero or more headers – name:value pairs on individual lines,
and then a blank line marking the end of headers. Those requests which involve
data upload -such as POST- then continue with the upload of the data. Then the
client waits for the server to respond.</p>
<p>The server can respond with an HTTP error code: a number, some headers of
its own, and then usually the body of the request. Usually the headers include
a MIME type declaration, and some others that are useful, such as
"content-length" and "expires".</p>
@@ -92,9 +80,7 @@
</section>
-<a name="JAX-RPC"/>
-<section>
-<title>JAX-RPC</title>
+<section name="JAX-RPC">
<p>The JAX-RPC specification is the base specification that client-side Axis
is built upon. If you are writing a client, read it.</p>
@@ -120,9 +106,7 @@
</section>
-<a name="Testing"/>
-<section>
-<title>Testing</title>
+<section name="Testing">
<p>If you want to test an Axis service, Wsdl2Java can be told to create a stub
JUnit test class, containing a test case for every single operation that the
remote service implements. These stub test cases need to be filled in with
valid test data, followed by the relevant assertions to validate the
results.</p>
@@ -136,18 +120,14 @@
</section>
-<a name="ConfiguringClient-sideHandlers"/>
-<section>
-<title>Configuring Client-side handlers</title>
+<section name="Configuring Client-side handlers">
<p><i>TODO</i></p>
<p>Axis supports both client side JAX-RPC and Axis handlers. These handlers
get called before a message is sent, and after it is received, just as for
server-side handlers.</p>
</section>
-<a name="Redistribution"/>
-<section>
-<title>Redistribution</title>
+<section name="Redistribution">
<p>To redistribute an application running Axis, you need to redistribute</p>
@@ -166,9 +146,7 @@
</section>
-<a name="DynamicallyDiscoveringAndBindingToAWebService"/>
-<section>
-<title>Dynamically Discovering and Binding to a Web Service</title>
+<section name="Dynamically Discovering and Binding to a Web Service">
<p>When Axis generates client proxy classes code from WSDL, it binds the code
to the endpoint URL specified in the WSDL -this is usually a URL generated from
the URL of the inbound request. Using a http://localhost URL to fetch a WSDL
page will result in client code also bound to a service served up on the
localhost, which is not what you want in a redistributable. Similarly, even if
you use the hostname when fetching the WSDL, you need the fully qualified
domain name, not any short name -http://s1.example.org/ and not http://s1/
-otherwise only callers in your own domain or subnet will be able to find the
server. Hand-written WSDL does not exhibit this problem; the endpoint in the
WSDL is the one the author typed in.</p>
@@ -180,17 +158,13 @@
</section>
-<a name="CallConfiguration"/>
-<section>
-<title>Call configuration</title>
+<section name="Call configuration">
<p>The Call object can be configured before a call can be made. The
<code>org.apache.axis.client.Call</code> is Axis's implementation of the
<code>javax.xml.rpc.Call</code> interface. The JAX-RPC standard interface
defines a <code>setProperty()</code> method that lets the caller set
properties; there are both JAX-RPC standard properties and Axis's own
properties that you can set.</p>
<p>All properties have a string name, a name defined in a public static final
declaration in the class.</p>
-<a name="StandardProperties"/>
-<section>
-<title>Standard Properties</title>
+<subsection name="Standard Properties">
<table width="100%" border="1" cellpadding="4" cellspacing="3">
<col width="85*"/>
@@ -290,11 +264,9 @@
</tbody>
</table>
-</section>
+</subsection>
-<a name="AxisProperties"/>
-<section>
-<title>Axis Properties</title>
+<subsection name="Axis Properties">
<table width="100%" border="1" cellpadding="4" cellspacing="3">
<col width="99*"/>
@@ -364,13 +336,11 @@
<p>You can still set these Axis-specific properties in a portable client
-other JAX-RPC implementations will not act on the options, of course.</p>
-</section>
+</subsection>
</section>
-<a name="NetworkConfiguration"/>
-<section>
-<title>Network configuration</title>
+<section name="Network configuration">
<p>Axis runs in a JVM, and JVM parameters control the client's behaviour. Here
are JVM configuration options that are used.</p>
@@ -410,7 +380,7 @@
<td width="42%" valign="top">
<p>Port on server of proxy</p>
</td>
- <td width="20%" valign="bottom" sdval="8080" sdnum="2057;">
+ <td width="20%" valign="bottom">
<p align="center">8080</p>
</td>
</tr>
@@ -444,7 +414,7 @@
<td width="42%" valign="top">
<p>Seconds to cache resolved hostnames;<br/>-1 == forever, 0==no
cache</p>
</td>
- <td width="20%" valign="bottom" sdval="120" sdnum="2057;">
+ <td width="20%" valign="bottom">
<p align="center">120</p>
</td>
</tr>
@@ -455,7 +425,7 @@
<td width="42%" valign="top">
<p>Seconds to cache unresolved hostnames;<br/>-1 == forever, 0==no
cache</p>
</td>
- <td width="20%" valign="bottom" sdval="30" sdnum="2057;">
+ <td width="20%" valign="bottom">
<p align="center">30</p>
</td>
</tr>
@@ -473,13 +443,11 @@
</section>
-<a name="TroubleshootingNetworkProblems"/>
-<section>
-<title>Troubleshooting Network Problems</title>
+<section name="Troubleshooting Network Problems">
<p>The classic definition of a distributed system:</p>
-<p>“<i>You know you have one when the crash of a computer you’ve
never heard of stops you from getting any work done.” Leslie
Lamport</i></p>
+<p>“<i>You know you have one when the crash of a computer you've never
heard of stops you from getting any work done.” Leslie Lamport</i></p>
<p>This may seem funny, but it is a depressingly accurate model of the state
of distributed systems. Everyone knows that web sites are sometimes off-line,
pages sometimes get served up incomplete or with some error trace instead of
the results.</p>
@@ -591,9 +559,7 @@
<p>Another useful technique is for the service to implement the
"Ping" design pattern. The service needs to support a simple
"ping" operation, that immediately returns. This operation can be
used by clients to probe for the presence of the service, without any other
side effects or even placing much load on the server. Client applications
should initiate communications with a server -uploads, complex requests, etc-
by pinging it first. This detects failure early on, hopefully at a lower
cost.</p>
-<a name="WhatCanTheDeveloperOfAWebServiceClientApplicationDo"/>
-<section>
-<title>What can the developer of a Web Service client application do?</title>
+<subsection name="What can the developer of a Web Service client application
do?">
<p>Networks are fundamentally unreliable; laptops move around and go offline,
services get switched off.</p>
@@ -611,9 +577,7 @@
<li>Look in the Java documents at "Address Caching" under
java.io.InetAddress. Applications need to be configured to only cache DNS
lookups, successful and unsuccessful, for a short period of time.</li>
</ol>
-</section>
-
-</section>
+</subsection>
</section>
