You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by st...@apache.org on 2003/03/20 00:20:26 UTC
cvs commit: xml-axis/java/docs install.html user-guide.html
stevel 2003/03/19 15:20:26
Modified: java/docs install.html user-guide.html
Log:
I am moderately concerned about the java competence level of many of the ant-user postings. While it is good that people new to java are rushing to Apache products, I feel it is important they know what a ClassNF Exception is, what a 404 error is (we do need to fix AdminClient to be more explanatory here :), and generally people should know how to write server side code before they start writing web services.
This patch spells out the prerequisite knowledge people need. It does try and scare people, because some of these people need to know that they cannot learn these things on a big project; it is like learning crampon, ice axe and glacier skills on a heavily crevassed, high-objective-hazard alpine peak.
Also I try and get my retaliation in early on what Axis and SOAP is, and what soap isnt (RMI over XML).
Revision Changes Path
1.26 +131 -17 xml-axis/java/docs/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/install.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- install.html 3 Mar 2003 15:50:40 -0000 1.25
+++ install.html 19 Mar 2003 23:20:25 -0000 1.26
@@ -53,27 +53,138 @@
<h2>Introduction</h2>
<p>This document describes how to install Apache Axis. It assumes
- you already know how to write and run Java code and not be scare
- of XML. You should also have an application server or servlet
- engine and be familiar with operating and deploying to it.
- If you need an application server, we recommend
- <a href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>.
- Other servlet engines are supported, provided they are version 2.2
- or greater. Note also that Axis client and server requires Java1.3
- or later.
+ you already know how to write and run Java code and not be scared
+ of XML. You should also have an application server or servlet
+ engine and be familiar with operating and deploying to it. If you
+ need an application server, we recommend <a
+ href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>. [If
+ you are installing tomcat, get the latest 4.1.x version, and the
+ full distribution, not the LE version for Java1.4, as that omits
+ the Xerces XML parser]. Other servlet engines are supported,
+ provided they implement version 2.2 or greater of the servlet API.
+ Note also that Axis client and server requires Java1.3 or later.
- <p>For more details on using Axis, please see the <a href="user-guide.html">user's
- guide</a>.
+ <p>For more details on using Axis, please see the
+ <a href="user-guide.html">user guide</a>.
+ <h2>Things you have to Know </h2>
+
+ A lot of problems with Axis are encountered by people who are new
+ to Java, Server-side Java and SOAP. While you can learn about SOAP
+ as you go along, writing Axis clients and serves is not the right
+ time to be learning foundational Java concepts, such as what an
+ array is, or foundation App server concepts such as how Servlets
+ work, and the basics of the HTTP protocol.
+ <p>
+ Things you need to know to begin to write a Web Service:
+ <ol>
+
+ <li> Core Java datatypes, classes and programming concepts.
+
+ <li> What threads are, race conditions, thread safety and
+ sychronization.
+
+ <li> What a classloader is, and what hierarchical classloaders are,
+ or 'common causes of a ClassNotFoundException'.
+
+ <li> How to diagnose trouble from exception traces, what a
+ NullPointerException (NPE) and other common exceptions are, and how
+ to fix them.
+
+ <li> What a web application is; what a servlet is, where classes,
+ libraries and data go in a web application.
+
+ <li> How to start your application server and deploy a web
+ application on it.
+
+ <li> What a network is, the core concepts of the IP protocol suite
+ and the sockets API. Specifically, what is TCP/IP.
+
+ <li> What HTTP is. The core protocol and error codes, HTTP headers and
+ perhaps the details of basic authentication.
+
+ <li> What XML is. Not how to parse it or anything, just what
+ constitutes well-formed and valid XML.
+
+ </ol>
+
+ Axis and SOAP depends on all these details. If you don't know them,
+ Axis (or anyone else's Web Service middleware) is a dangerous place
+ to learn. Sooner or later you will be forced to discover these
+ details, and there are easier places to learn than Axis.
+
+ <p>
+
+ If you are completely new to Java, we recommend you start off with
+ things like the Java Tutorials on Sun's web sites, and perhaps a
+ classic book like <a
+ href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>,
+ until you have enough of a foundation to be able to work with
+ Axis. It is also useful to have written a simple web application,
+ as this will give you some knowledge of how HTTP works, and how
+ Java applications servers integrate with HTTP.
+
+ <p>
+
+ Be aware that there is a lot more to know to use Axis and SOAP
+ effectively than the listing above. The other big area is "how to
+ write internet scale distributed applications". Nobody knows how to
+ do that properly yet, so that you have to learn by doing.
+
<h2>Step 0: Concepts</h2>
- Axis is implemented in the JAR file <i>axis.jar</i>; implementing the
- JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and <i>saaj.jar</i>. It
- needs various helper libraries, for logging, WSDL processing and
- introspection. All these files can be packaged into a
- web application, <i>axis.war</i>, that can be dropped into a servlet container.
- Axis ships with some sample SOAP services. You can
- add your own by adding new compiled classes to the Axis webapp registering them.
+ Apache Axis is an Open Source SOAP server and client. SOAP is a
+ mechanism for inter-application communication between systems
+ written in arbitrary languages, across the Internet. SOAP usually
+ exchanges messages over HTTP: the client POSTs a SOAP request, and
+ receives either an HTTP error code or an HTTP success code and a
+ SOAP response.
+
+ <p>
+
+ SOAP messages are XML messages. These messages exchange structured
+ information between SOAP systems. Messages consist of one or more
+ SOAP elements inside an envelope, Headers and the SOAP Body.
+ SOAP has two syntaxes for describing the data in these elements,
+ <i>Section 5</i>, which is a clear descendent of the XML RPC
+ system, and <i>XML Schema</i>, which is the newer (and usually
+ better) system. Axis handles the magic of converting Java objects
+ to SOAP data when it sends it over the wire or receives results.
+ SOAP Faults are sent by the server when something goes wrong; Again
+ Axis converts these to Java exceptions.
+
+ <p>
+
+ SOAP is intended to link disparate systems. It is not a mechanism
+ to tightly bind Java programs written by the same team together. It
+ can bind Java programs together, but not as tightly as RMI or
+ Corba. If you try sending many Java objects that RMI would happily
+ serialize, you will be disappointed at how badly Axis fails. This
+ is by design: if Axis copied RMI and serialized Java objects to
+ byte streams, you would be stuck to a particular version of Java
+ everywhere.
+
+ <p>
+
+ Axis implements the JAX-RPC API, one of the standard ways to program
+ Java services. If you look at the specification and tutorials on
+ Sun's web site, you will understand the API. If you code to the
+ API, your programs will work with other implementations of the API,
+ such as those by Sun and BEA. Axis also provides extension
+ features, and many ways that extend the JAX-RPC API. You can use
+ these to write better programs, ones that only work with Axis. But
+ since Axis is free and you get the source, that should not matter.
+
+ <p>
+
+ Axis is implemented in the JAR file <i>axis.jar</i>; implementing
+ the JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and
+ <i>saaj.jar</i>. It needs various helper libraries, for logging,
+ WSDL processing and introspection. All these files can be packaged
+ into a web application, <i>axis.war</i>, that can be dropped into a
+ servlet container. Axis ships with some sample SOAP services. You
+ can add your own by adding new compiled classes to the Axis webapp
+ registering them.
<p>
Before you can do that, you have to install it and get it working.
@@ -148,6 +259,9 @@
Axis will not work. <br><b>You must not proceed until all needed libraries
can be found, and this validation page is happy.</b> <br>
Optional components are optional; install them as your need arises.
+ If you see nothing but an internal server error and an exception
+ trace, then you probably have multiple XML parsers on the
+ classpath, and this is causing version confusion.
<h3>Look for some services</h3>
From the start page, select <i>View the list of deployed Web services</i>.
1.82 +8 -8 xml-axis/java/docs/user-guide.html
Index: user-guide.html
===================================================================
RCS file: /home/cvs/xml-axis/java/docs/user-guide.html,v
retrieving revision 1.81
retrieving revision 1.82
diff -u -r1.81 -r1.82
--- user-guide.html 15 Mar 2003 05:59:16 -0000 1.81
+++ user-guide.html 19 Mar 2003 23:20:25 -0000 1.82
@@ -156,13 +156,13 @@
(note: if you build axis from a CVS checkout,
these will be in xml-axis/java/build/lib instead of axis-1_0/lib):
<ul>
-<li>axis-1_0/lib/axis.jar</li>
-<li>axis-1_0/lib/jaxrpc.jar</li>
-<li>axis-1_0/lib/saaj.jar</li>
-<li>axis-1_0/lib/commons-logging.jar</li>
-<li>axis-1_0/lib/commons-dicovery.jar</li>
-<li>axis-1_0/lib/wsdl4j.jar</li>
- <li>axis-1_0/ <i><font color="#9966FF">(for the sample code)</font></i></li>
+<li>axis-1_1/lib/axis.jar</li>
+<li>axis-1_1/lib/jaxrpc.jar</li>
+<li>axis-1_1/lib/saaj.jar</li>
+<li>axis-1_1/lib/commons-logging.jar</li>
+<li>axis-1_1/lib/commons-dicovery.jar</li>
+<li>axis-1_1/lib/wsdl4j.jar</li>
+ <li>axis-1_1/ <i><font color="#9966FF">(for the sample code)</font></i></li>
<li>A JAXP-1.1 compliant XML parser such as xerces or crimson</li>
</ul>
<h2>
@@ -715,7 +715,7 @@
<h5>Java Collections</h5>
-Some of the Collection classes, such as <tt>HashTable</tt> do have
+Some of the Collection classes, such as <tt>Hashtable</tt> do have
serializers, but there is no formal interoperability with other SOAP
implementations, and nothing in the SOAP specifications which covers
complex objects. The most reliable way to send aggregate objects is to
Re: cvs commit: xml-axis/java/docs install.html user-guide.html
Posted by Steve Loughran <st...@iseran.com>.
----- Original Message -----
From: "Davanum Srinivas" <di...@yahoo.com>
To: <ax...@ws.apache.org>
Sent: Wednesday, March 19, 2003 17:07
Subject: Re: cvs commit: xml-axis/java/docs install.html user-guide.html
> s/ant-user/axis-user/g right?
yes. Actually the ant-users are more java aware...by the time you are into
ant/XML-based build processes you tend to know a bit more about the java.
But on our mail list we see people who dont recognise a 404 response from
AdminClient, or know what to do when they get a ClassNotFound exception.
That said, who has noticed the 50 line message that ant1.5 prints when it
cannot instantiate some task like junit because junit.jar is missing, which
starts with a list of common causes and ends with 'do not file this as a a
bug'.
While I celebrate the fact that open source tools and technologies lower the
barriers of entry to becoming a Java developer, I do fear for the stability
and security of the systems they are building.
Once Axis1.1 ships I'll add the HappyClient test code to the 1.2 codebase.
We should consider making AxisClient more informative...I filed an
enhancement req a bit back about how http errors should be handled better
(add the error code as a fault element), so we can analyse the result and
print more helpful clues. Like 'look at this in a web browser' before
escalating.
-steve
Re: cvs commit: xml-axis/java/docs install.html user-guide.html
Posted by Davanum Srinivas <di...@yahoo.com>.
s/ant-user/axis-user/g right?
--- stevel@apache.org wrote:
> stevel 2003/03/19 15:20:26
>
> Modified: java/docs install.html user-guide.html
> Log:
> I am moderately concerned about the java competence level of many of the ant-user postings.
> While it is good that people new to java are rushing to Apache products, I feel it is important
> they know what a ClassNF Exception is, what a 404 error is (we do need to fix AdminClient to be
> more explanatory here :), and generally people should know how to write server side code before
> they start writing web services.
>
> This patch spells out the prerequisite knowledge people need. It does try and scare people,
> because some of these people need to know that they cannot learn these things on a big project;
> it is like learning crampon, ice axe and glacier skills on a heavily crevassed,
> high-objective-hazard alpine peak.
>
> Also I try and get my retaliation in early on what Axis and SOAP is, and what soap isnt (RMI
> over XML).
>
> Revision Changes Path
> 1.26 +131 -17 xml-axis/java/docs/install.html
>
> Index: install.html
> ===================================================================
> RCS file: /home/cvs/xml-axis/java/docs/install.html,v
> retrieving revision 1.25
> retrieving revision 1.26
> diff -u -r1.25 -r1.26
> --- install.html 3 Mar 2003 15:50:40 -0000 1.25
> +++ install.html 19 Mar 2003 23:20:25 -0000 1.26
> @@ -53,27 +53,138 @@
> <h2>Introduction</h2>
>
> <p>This document describes how to install Apache Axis. It assumes
> - you already know how to write and run Java code and not be scare
> - of XML. You should also have an application server or servlet
> - engine and be familiar with operating and deploying to it.
> - If you need an application server, we recommend
> - <a href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>.
> - Other servlet engines are supported, provided they are version 2.2
> - or greater. Note also that Axis client and server requires Java1.3
> - or later.
> + you already know how to write and run Java code and not be scared
> + of XML. You should also have an application server or servlet
> + engine and be familiar with operating and deploying to it. If you
> + need an application server, we recommend <a
> + href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>. [If
> + you are installing tomcat, get the latest 4.1.x version, and the
> + full distribution, not the LE version for Java1.4, as that omits
> + the Xerces XML parser]. Other servlet engines are supported,
> + provided they implement version 2.2 or greater of the servlet API.
> + Note also that Axis client and server requires Java1.3 or later.
>
> - <p>For more details on using Axis, please see the <a href="user-guide.html">user's
> - guide</a>.
> + <p>For more details on using Axis, please see the
> + <a href="user-guide.html">user guide</a>.
>
> + <h2>Things you have to Know </h2>
> +
> + A lot of problems with Axis are encountered by people who are new
> + to Java, Server-side Java and SOAP. While you can learn about SOAP
> + as you go along, writing Axis clients and serves is not the right
> + time to be learning foundational Java concepts, such as what an
> + array is, or foundation App server concepts such as how Servlets
> + work, and the basics of the HTTP protocol.
> + <p>
> + Things you need to know to begin to write a Web Service:
> + <ol>
> +
> + <li> Core Java datatypes, classes and programming concepts.
> +
> + <li> What threads are, race conditions, thread safety and
> + sychronization.
> +
> + <li> What a classloader is, and what hierarchical classloaders are,
> + or 'common causes of a ClassNotFoundException'.
> +
> + <li> How to diagnose trouble from exception traces, what a
> + NullPointerException (NPE) and other common exceptions are, and how
> + to fix them.
> +
> + <li> What a web application is; what a servlet is, where classes,
> + libraries and data go in a web application.
> +
> + <li> How to start your application server and deploy a web
> + application on it.
> +
> + <li> What a network is, the core concepts of the IP protocol suite
> + and the sockets API. Specifically, what is TCP/IP.
> +
> + <li> What HTTP is. The core protocol and error codes, HTTP headers and
> + perhaps the details of basic authentication.
> +
> + <li> What XML is. Not how to parse it or anything, just what
> + constitutes well-formed and valid XML.
> +
> + </ol>
> +
> + Axis and SOAP depends on all these details. If you don't know them,
> + Axis (or anyone else's Web Service middleware) is a dangerous place
> + to learn. Sooner or later you will be forced to discover these
> + details, and there are easier places to learn than Axis.
> +
> + <p>
> +
> + If you are completely new to Java, we recommend you start off with
> + things like the Java Tutorials on Sun's web sites, and perhaps a
> + classic book like <a
> + href="http://www.mindview.net/Books/TIJ/">Thinking in Java</a>,
> + until you have enough of a foundation to be able to work with
> + Axis. It is also useful to have written a simple web application,
> + as this will give you some knowledge of how HTTP works, and how
> + Java applications servers integrate with HTTP.
> +
> + <p>
> +
> + Be aware that there is a lot more to know to use Axis and SOAP
> + effectively than the listing above. The other big area is "how to
> + write internet scale distributed applications". Nobody knows how to
> + do that properly yet, so that you have to learn by doing.
> +
> <h2>Step 0: Concepts</h2>
>
> - Axis is implemented in the JAR file <i>axis.jar</i>; implementing the
> - JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and <i>saaj.jar</i>. It
> - needs various helper libraries, for logging, WSDL processing and
> - introspection. All these files can be packaged into a
> - web application, <i>axis.war</i>, that can be dropped into a servlet container.
> - Axis ships with some sample SOAP services. You can
> - add your own by adding new compiled classes to the Axis webapp registering them.
> + Apache Axis is an Open Source SOAP server and client. SOAP is a
> + mechanism for inter-application communication between systems
> + written in arbitrary languages, across the Internet. SOAP usually
> + exchanges messages over HTTP: the client POSTs a SOAP request, and
> + receives either an HTTP error code or an HTTP success code and a
> + SOAP response.
> +
> + <p>
> +
> + SOAP messages are XML messages. These messages exchange structured
> + information between SOAP systems. Messages consist of one or more
> + SOAP elements inside an envelope, Headers and the SOAP Body.
> + SOAP has two syntaxes for describing the data in these elements,
> + <i>Section 5</i>, which is a clear descendent of the XML RPC
> + system, and <i>XML Schema</i>, which is the newer (and usually
> + better) system. Axis handles the magic of converting Java objects
> + to SOAP data when it sends it over the wire or receives results.
> + SOAP Faults are sent by the server when something goes wrong; Again
> + Axis converts these to Java exceptions.
> +
> + <p>
> +
> + SOAP is intended to link disparate systems. It is not a mechanism
> + to tightly bind Java programs written by the same team together. It
> + can bind Java programs together, but not as tightly as RMI or
> + Corba. If you try sending many Java objects that RMI would happily
> + serialize, you will be disappointed at how badly Axis fails. This
> + is by design: if Axis copied RMI and serialized Java objects to
> + byte streams, you would be stuck to a particular version of Java
> + everywhere.
> +
> + <p>
> +
> + Axis implements the JAX-RPC API, one of the standard ways to program
> + Java services. If you look at the specification and tutorials on
> + Sun's web site, you will understand the API. If you code to the
> + API, your programs will work with other implementations of the API,
> + such as those by Sun and BEA. Axis also provides extension
> + features, and many ways that extend the JAX-RPC API. You can use
> + these to write better programs, ones that only work with Axis. But
> + since Axis is free and you get the source, that should not matter.
> +
> + <p>
> +
> + Axis is implemented in the JAR file <i>axis.jar</i>; implementing
> + the JAX-RPC API declared in the JAR files <i>jaxrpc.jar</i> and
> + <i>saaj.jar</i>. It needs various helper libraries, for logging,
> + WSDL processing and introspection. All these files can be packaged
> + into a web application, <i>axis.war</i>, that can be dropped into a
> + servlet container. Axis ships with some sample SOAP services. You
> + can add your own by adding new compiled classes to the Axis webapp
> + registering them.
>
> <p>
> Before you can do that, you have to install it and get it working.
> @@ -148,6 +259,9 @@
> Axis will not work. <br><b>You must not proceed until all needed libraries
> can be found, and this validation page is happy.</b> <br>
> Optional components are optional; install them as your need arises.
> + If you see nothing but an internal server error and an exception
> + trace, then you probably have multiple XML parsers on the
> + classpath, and this is causing version confusion.
>
> <h3>Look for some services</h3>
> From the start page, select <i>View the list of deployed Web services</i>.
>
>
>
> 1.82 +8 -8 xml-axis/java/docs/user-guide.html
>
> Index: user-guide.html
>
=== message truncated ===
=====
Davanum Srinivas - http://webservices.apache.org/~dims/
__________________________________________________
Do you Yahoo!?
Yahoo! Platinum - Watch CBS' NCAA March Madness, live on your desktop!
http://platinum.yahoo.com