CVS: ivory/xdocs axis-how.xml,NONE,1.1 navigation.xml,1.1,1.2 axiscomponent.xml,1.5,1.6
[email protected] Mon, 5 May 2003 09:19:12 -0500
| Newsgroups | gmane.comp.java.plexus.devel |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/plexus/ivory/xdocs
In directory eng.werken.com:/tmp/cvs-serv1379/xdocs
Modified Files:
navigation.xml axiscomponent.xml
Added Files:
axis-how.xml
Log Message:
Ivory is really coming along now...
There is now an IvoryProvider which loads the IvoryServiceDesc
instead of Axis's ServiceDesc. The IvoryServiceDesc has
metadata capabilities. Currently you can specify to not expose
certain methods as a web service and also specify what type of
array a List should be serialized to (hooray!).
NOTE: You now need commons-attributes installed in your maven
repo! This is only available from apache CVS currently. See:
http://jakarta.apache.org/commons/sandbox/attributes
Also, there are a bunch of documentation improvements, with
more coming.
--- NEW FILE: axis-how.xml ---
<?xml version="1.0"?>
<document>
<properties>
<title>How it works</title>
<author email="[email protected]">Dan Diephouse</author>
</properties>
<body>
<section name="How it works">
<p>
In a normal HTTP type Axis situation, the AxisServlet is soley
responsible for taking care of loading Axis. It uses the a
WSDD file to configure the AxisEngine and provides an interface
to that AxisEngine through HTTP requests.
</p>
<p>
However, in the AxisService we embed the AxisEngine (aka, the
AxisServer) into an Avalon component. By doing so we are able
to do two things. First, we are able to provide the AxisServer to the
servlets as well as avalon components. There are classes in the
org.apache.ivory.axis.servlet package which extend the Axis servlets
so we can look up the AxisService and provide the servlets
with the AxisEngine. Second, we are able to use the AxisEngine in our service
to dynamically configure components as SOAP services. This is the real
meat of the Axis component.
</p>
<subsection name="Internal Axis Configuration">
<p>
Axis's primary mode of configuration resolves around WSDD
deployment descriptors. Normally, the AdminServlet is the primary
point of service deployment and undeployment using WSDD. The WSDD
configuration model is somewhat intertwined all throughout Axis. While
Axis starts to have its own internal configuration model, it fails in
some respects.
</p>
<p>
The good news is that it is still workable to have a configuration
model other than WSDD. If this wasn't possible you would have to
deploy all your services through WSDD and wouldn't be able to
dynamically expose them.
</p>
<p>
The AxisService uses the class
org.apache.axis.configuration.SimpleProvider as its configuration model
for the AxisServer. The SimpleProvider allows us to deploy
services on the fly easily without resorting to WSDD.
</p>
</subsection>
<subsection name="Creating the service">
<p>
The SOAPService class is fundamental to creating services
dynamically with Axis. The javadocs have something good to say
on this topic: <i>A SOAPService is a Handler which encapsulates a SOAP
invocation. It has an request chain, an response chain, and a pivot-point,
and handles the SOAP semantics when invoke()d.</i>
This means the SOAPService is the central starting point for any
service. It handles what happens when your service is invoked.
However, a lot of the magic happens in the providers, detailed
in the next section.
</p>
</subsection>
<subsection name="Axis Providers">
<p>
Axis contains several default service handlers which encapsulate services.
They are usually called "Providers." These providers are responsible
for the actual instantiation of your java classes that the soap xml maps to
(Serialization is handled by the TypeMapping and other
org.apache.axis.encoding.* classes).
</p>
<p>
By setting the appropriate options on the SOAPService (which is the
encapsulation of a SOAP invocation) we are able to create new
services relatively easily (see DefaultAxisService). However, if we
are exposing Avalon services we need to use a different provider other
than the JavaProvider bundled with Axis. The AvalonProvider extends
JavaProvider to do this. Instead of creating new objects, it just
finds the object in the service manager.
</p>
</subsection>
<subsection name="Serialization">
<p>
Currently, the AxisService relies solely on Bean(De)serializers to
do the mapping from XML to the java class or component. Hopefully
this will be made more flexible in the future. In the meantime,
your SOAP Services must be in the java bean format and you can't
hide anything from Axis. All methods are exposed.
</p>
</subsection>
</section>
</body>
</document>
Index: navigation.xml
===================================================================
RCS file: /cvsroot/plexus/ivory/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- navigation.xml 18 Mar 2003 00:04:33 -0000 1.1
+++ navigation.xml 5 May 2003 14:19:06 -0000 1.2
@@ -5,12 +5,17 @@
<body>
<links>
+ <item name="Blog" href="http://blogs.codehaus.org/projects/ivory"/>
<item name="Plexus" href="http://plexus.werken.com"/>
</links>
<menu name="Overview">
<item name="Main" href="/index.html"/>
- <item name="Axis Avalon Component" href="/axiscomponent.html"/>
+ </menu>
+
+ <menu name="Axis Avalon Component">
+ <item name="Quick Start" href="/axiscomponent.html"/>
+ <item name="Developer's Guide" href="/axis-how.html"/>
</menu>
</body>
Index: axiscomponent.xml
===================================================================
RCS file: /cvsroot/plexus/ivory/xdocs/axiscomponent.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- axiscomponent.xml 4 May 2003 20:25:56 -0000 1.5
+++ axiscomponent.xml 5 May 2003 14:19:06 -0000 1.6
@@ -41,9 +41,20 @@
]]></source>
</p>
<p>
- where an <avalonService> is loaded through the Avalon ServiceManager
- and a <classService> is loaded through the ClassLoader. The "name"
- attribute specifies the name of the exposed SOAP service.
+ where an <avalonService> is loaded through the Avalon ServiceManager
+ and a <classService> is loaded through the ClassLoader. The "name"
+ attribute specifies the name of the exposed SOAP service.
+ </p>
+ <p>
+ After that you will need to configure your view medium, most likely
+ a servlet. There are Axis servlets for
+ <a href="http://plexus.codehuas.org">Plexus</a> in CVS. Patches for
+ for other Avalon containers are very welcome. After the appropriate
+ entries in your web.xml are entered, point your browser at the
+ service WSDL generation. The URL is generally something like
+ "http://localhost/app/services/ServiceName?wsdl", depending on how
+ you map the servlets. See the web.xml in src/conf in the source
+ distribution.
</p>
</subsection>
<subsection name="Security">
@@ -65,24 +76,41 @@
</p>
</subsection>
</section>
- <section name="Ideas">
+ <section name="Axis Metadata Directives">
<p>
- Possible ideas for improvement of this component:
- <ul>
- <li>
- Use attributes or xml to specify which methods should be
- serialized for the SOAP service. Currently the only option
- is to use the Bean(De)Serializers.
- </li>
- <li>
- Transparent security mechanisms.
- </li>
- <li>
- Create a proxy for the classes and components being exposed.
- This would allow less dependence on introspection and speed
- up the services.
- </li>
- </ul>
+ Because Java and XML don't always match up the Axis component now allows
+ you to put metadata in your code thanks to
+ <a href="http://qdox.sourceforge.net">QDox</a> and
+ <a href="http://jakarta.apache.org/commons/sandbox/attributes">Common's
+ Attributes</a>. There are two directives you can put in your code currently.
+ <table>
+ <tbody>
+ <tr>
+ <th>Directive</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>@axis.serialize.[param] [ObjectType]</td>
+ <td>
+ This directive tells the component to serialize the specified parameter
+ [param] as the specified [ObjectType]. This needs to be done for any
+ method that takes or returns a List. Axis needs to know what kind
+ of array to serialize the List to. For example, specifying
+ "@axis.serialize.out [Ljava.lang.String;" would mean serialize the
+ returned List as an array of Strings. Or
+ "@axis.serialize.in0 [Lcom.company.Employee;" would mean serialize the
+ first parameter for the method as an array of Employee objects.
+ </td>
+ </tr>
+ <tr>
+ <td>@axis.hidemethod</td>
+ <td>
+ This directive tells the the Axis component to not expose the
+ method as a web service.
+ </td>
+ </tr>
+ </tbody>
+ </table>
</p>
</section>
<section name="Bugs">
@@ -97,97 +125,14 @@
<a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=18084 ">Bug 18084.</a>
</li>
<li>
- There is no control over serialization right now. The service
- exposes every bean method available on your objects. There should be
- a way to prevent certain methods from being exposed.
- </li>
- <li>
The servlets leave a little bit to be desired yet. For example, the
service name will come up as "null."
</li>
<li>
- Components need to be ThreadSafe right now.
+ Exposed avalon services need to be ThreadSafe right now.
</li>
</ul>
</p>
- </section>
- <section name="How it works">
- <p>
- In a normal HTTP type Axis situation, the AxisServlet is soley
- responsible for taking care of loading Axis. It uses the a
- WSDD file to configure the AxisEngine and provides an interface
- to that AxisEngine through HTTP requests.
- </p>
- <p>
- However, in the AxisService we embed the AxisEngine (aka, the
- AxisServer) into an Avalon component. By doing so we are able
- to do two things. First, we are able to provide the AxisServer to the
- servlets as well as avalon components. There are classes in the
- org.apache.ivory.axis.servlet package which extend the Axis servlets
- so we can look up the AxisService and provide the servlets
- with the AxisEngine. Second, we are able to use the AxisEngine in our service
- to dynamically configure components as SOAP services. This is the real
- meat of the Axis component.
- </p>
- <subsection name="Internal Axis Configuration">
- <p>
- Axis's primary mode of configuration resolves around WSDD
- deployment descriptors. Normally, the AdminServlet is the primary
- point of service deployment and undeployment using WSDD. The WSDD
- configuration model is somewhat intertwined all throughout Axis. While
- Axis starts to have its own internal configuration model, it fails in
- some respects.
- </p>
- <p>
- The good news is that it is still workable to have a configuration
- model other than WSDD. If this wasn't possible you would have to
- deploy all your services through WSDD and wouldn't be able to
- dynamically expose them. The AxisService uses the class
- org.apache.axis.configuration.SimpleProvider as its configuration model
- for the AxisServer. The SimpleProvider allows us to deploy
- services on the fly easily without resorting to WSDD.
- </p>
- </subsection>
- <subsection name="Creating the service">
- <p>
- The SOAPService class is fundamental to creating services
- dynamically with Axis. The javadocs have something good to say
- on this topic: <i>A SOAPService is a Handler which encapsulates a SOAP
- invocation. It has an request chain, an response chain, and a pivot-point,
- and handles the SOAP semantics when invoke()d.</i>
- This means the SOAPService is the central starting point for any
- service. It handles what happens when your service is invoked.
- However, a lot of the magic happens in the providers, detailed
- in the next section.
- </p>
- </subsection>
- <subsection name="Axis Providers">
- <p>
- Axis contains several default service handlers which encapsulate services.
- They are usually called "Providers." These providers are responsible
- for the actual instantiation of your java classes that the soap xml maps to
- (Serialization is handled by the TypeMapping and other
- org.apache.axis.encoding.* classes).
- </p>
- <p>
- By setting the appropriate options on the SOAPService (which is the
- encapsulation of a SOAP invocation) we are able to create new
- services relatively easily (see DefaultAxisService). However, if we
- are exposing Avalon services we need to use a different provider other
- than the JavaProvider bundled with Axis. The AvalonProvider extends
- JavaProvider to do this. Instead of creating new objects, it just
- finds the object in the service manager.
- </p>
- </subsection>
- <subsection name="Serialization">
- <p>
- Currently, the AxisService relies solely on Bean(De)serializers to
- do the mapping from XML to the java class or component. Hopefully
- this will be made more flexible in the future. In the meantime,
- your SOAP Services must be in the java bean format and you can't
- hide anything from Axis. All methods are exposed.
- </p>
- </subsection>
</section>
</body>
</document>