Return-Path: X-Original-To: apmail-maven-commits-archive@www.apache.org Delivered-To: apmail-maven-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 2EB9F95AC for ; Thu, 1 Mar 2012 18:57:40 +0000 (UTC) Received: (qmail 44959 invoked by uid 500); 1 Mar 2012 18:57:40 -0000 Delivered-To: apmail-maven-commits-archive@maven.apache.org Received: (qmail 44884 invoked by uid 500); 1 Mar 2012 18:57:40 -0000 Mailing-List: contact commits-help@maven.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@maven.apache.org Delivered-To: mailing list commits@maven.apache.org Received: (qmail 44877 invoked by uid 99); 1 Mar 2012 18:57:40 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Mar 2012 18:57:40 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 01 Mar 2012 18:57:27 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id B88AB2388AB8 for ; Thu, 1 Mar 2012 18:57:04 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r806928 [5/8] - in /websites/staging/maventest-doxia/trunk: ./ content/ content/book/ content/css/ content/developers/ content/doxia-example-book/ content/images/ content/images/logos/ content/issues/ content/macros/ content/modules/ conten... Date: Thu, 01 Mar 2012 18:57:02 -0000 To: commits@maven.apache.org From: buildbot@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20120301185704.B88AB2388AB8@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/http-transport.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/http-transport.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/http-transport.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,200 @@ + + + + + HTTP Transport + + + + + + + + + + + + + +
+ +
+
+
+

HTTP Transport

XFireServlet

The core of the HTTP Transport takes place in the XFireServletController. Your own servlets can delegate appropriate requests to this class or you can use one of XFire's internal servlet classes. The XFireServlet is just a thin wrapper for the controller. The XFireServletController provides an xml configuration layer on top of this.

XFire also provides the XFireConfigurableServlet which reads the services.xml format automatically for you and the XFireSpringServlet which provides Sprign integration.

HttpServletRequest/HttpServletResponse

The HttpServletRequest/HttpServletResponse can be accessed via the XFireServletController.

HttpServletRequest request = XFireServletController.getRequest();
+HttpServletResponse response = XFireServletController.getResponse();

This method will work all the XFire servlets (XFireServlet, XFireConfigurableServlet, XFireSpringServlet).

Client authentication

The Apache Jakarta HttpClient is used under the covers to provide HTTP client support. There are two ways which you can override the HttpClient settings:

  1. You can set the USERNAME/PASSWORD
    // Create your client
    +Client client = ....;
    +
    +// Or get it from your proxy
    +Client client = ((XFireProxy) Proxy.getInvocationHandler(myClientProxy)).getClient();
    +
    +client.setProperty(Channel.USERNAME, "username");
    +client.setProperty(Channel.PASSWORD, "pass");
  2. You can supply your own HttpClientParms
    client.setProperty(CommonsHttpMessageSender.HTTP_CLIENT_PARAMS, myParams);

    The HTTPClient javadocs provide information on how to configure the HttpClientParams.

Proxy Support

Proxy support looks very similar to the username/password scenario:

// Create your client
+Client client = ....;
+
+// Or get it from your proxy
+Client client = ((XFireProxy) Proxy.getInvocationHandler(myClientProxy)).getClient();
+client.setProperty(CommonsHttpMessageSender.HTTP_PROXY_HOST, "host");
+client.setProperty(CommonsHttpMessageSender.HTTP_PROXY_PORT, "8080");

HTTP Chunking

You'll need to enable HTTP chunking on the client if you are sending large files which can't be cached in memory:

import org.codehaus.xfire.transport.http.HttpTransport;
+
+Client client = ....;
+client.setProperty(HttpTransport.CHUNKING_ENABLED, "true");
+
+
+
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/index.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/index.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/index.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,182 @@ + + + + + XFire User Manual - Table Of Content + + + + + + + + + + + + +
+ +
+ +
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/jms-transport.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/jms-transport.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/jms-transport.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,265 @@ + + + + + JMS Transport + + + + + + + + + + + + + +
+ +
+
+
+

JMS Transport

This guide gives you a quick rundown of how to configure XFire to use JMS as a transport. JMS is one of the easiest means to create a reliable SOAP connection. Additionally it is much faster then things such as WS-Reliability.

This example assumes that you already know how to:

  • Configure services via XFire's services.xml format
  • Build and deploy simple XFire applications
  • Use your JMS provider
  • A working knowledge of Spring

We're just go ing to show a simple synchronous Echo example running over JMS. The first thing you need to do is create your services.xml file:

<beans xmlns="http://xfire.codehaus.org/config/1.0">
+
+  <!--
+    Register the JMS transport. Note: this needs to happen *before* we
+    create our service.
+    -->
+  <xfire>
+    <transports>
+      <bean id="jmsTransport"
+            class="org.codehaus.xfire.transport.jms.JMSTransport"
+            xmlns="http://xbean.org/schemas/spring/1.0">
+        <constructor-arg ref="xfire"/>
+        <constructor-arg ref="connectionFactory"/>
+      </bean>
+    </transports>
+  </xfire>
+
+  <service xmlns:e="urn:Echo">
+    <name>Echo</name>
+    <serviceClass>org.codehaus.xfire.test.Echo</serviceClass>
+    <implementationClass>org.codehaus.xfire.test.EchoImpl</implementationClass>
+    <bindings>
+      <soap11Binding name="e:EchoJMSBinding" transport="urn:xfire:transport:jms">
+        <endpoints>
+          <endpoint name="e:EchoJMSEndpoint" url="jms://Echo" />
+        </endpoints>
+      </soap11Binding>
+    </bindings>
+  </service>
+
+  <bean id="connectionFactory"
+        class="org.apache.activemq.ActiveMQConnectionFactory"
+        singleton="true"
+        xmlns="http://xbean.org/schemas/spring/1.0/">
+    <constructor-arg value="vm://localhost?broker.persistent=false" type="java.lang.String"/>
+  </bean>
+
+</beans>

There is a lot in here, so lets recap this a little bit.

The xfire section contains a transports element. In transports we are creating our JMSTransport via the Spring bean syntax. XFire will then automatically register this transport for us into the TransportManager.

The service element contains our service definition. This is pretty standard, except you'll notice we're creating a new binding for JMS. soap11Binding transport="urn:xfire:transport:jms" tells XFire that we want to add a SOAP 1.1 binding for JMS. In the endpoints section we tell XFire exactly what that endpoint will be. The JMS urls take the form of jms://QueueName.

In the sections below we configure our JMS QueueConnectionFactory using ActiveMQ.

Once all of this is properly configured we will of course want to write a client:

import java.lang.reflect.Proxy;
+
+import org.codehaus.xfire.client.XFireProxy;
+import org.codehaus.xfire.client.XFireProxyFactory;
+import org.codehaus.xfire.service.Service;
+import org.codehaus.xfire.service.binding.ObjectServiceFactory;
+import org.codehaus.xfire.spring.AbstractXFireSpringTest;
+import org.codehaus.xfire.test.Echo;
+import org.codehaus.xfire.transport.jms.JMSTransport;
+import org.springframework.context.ApplicationContext;
+import org.apache.xbean.spring.context.ClassPathXmlApplicationContext;
+
+public class JMSExampleTest
+    extends AbstractXFireSpringTest
+{
+    protected ApplicationContext createContext()
+    {
+        return new ClassPathXmlApplicationContext(new String[] {
+                "/org/codehaus/xfire/transport/jms/example/jms.xml",
+                "/org/codehaus/xfire/spring/xfire.xml" });
+    }
+
+    public void testClient()
+            throws Exception
+    {
+        // Create a ServiceFactory to create the ServiceModel.
+        // We need to add the JMSTransport to the list of bindings to create.
+        ObjectServiceFactory sf = new ObjectServiceFactory(getTransportManager());
+        sf.addSoap11Transport(JMSTransport.BINDING_ID);
+
+        // Create the service model
+        Service serviceModel = sf.create(Echo.class);
+
+        // Create a proxy for the service
+        XFireProxyFactory factory = new XFireProxyFactory(getXFire());
+        Echo echo = (Echo) factory.create(serviceModel, "jms://Echo");
+
+        // Since JMS doesn't really have a concept of anonymous endpoints, we need
+        // need to let xfire know what JMS endpoint we should use
+        ((XFireProxy) Proxy.getInvocationHandler(echo)).getClient().setEndpointUri("jms://Peer1");
+
+        // run the client!
+        String resString = echo.echo("hello");
+        assertEquals("hello", resString);
+    }
+}
+
+
+
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/local-transport.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/local-transport.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/local-transport.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,186 @@ + + + + + Local Transport + + + + + + + + + + + + + +
+ +
+
+
+

Previous: JMS TransportUp: TransportsEnd of book

Local Transport

XFire includes an in-JVM transport called the LocalTransport. If you are using the XFire client or the Channel API, you can address a local service like so:

xfire.local://FooService

For example, when creating a service:

Service service = getServiceRegistry().getService("FooService");
+
+XFireProxyFactory factory = new XFireProxyFactory(getXFire());
+FooService foo = (FooService) factory.create(service, "xfire.local://FooService");


Previous: JMS TransportUp: TransportsEnd of book
+
+
+
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/transport-and-channel-api.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/transport-and-channel-api.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/transport-and-channel-api.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,189 @@ + + + + + Transport and Channel API + + + + + + + + + + + + + +
+ +
+
+
+

Transports and Channels

Channels and Transports provide the basic unit of communication in XFire. A Channel simply sends messages (via send()) and listens for messages (via receive()). If you want to send a message to a particular URL you do:

TransportManager tm = ...;
+Transport t = tm.getTransportForUri("http://foo");
+
+OutMessage msg = ...; // create an outmessage yourself
+Channel c = t.createChannel(); // create an anonymous endpoint
+MessageContext context = new MessageContext();
+c.send(msg, context);

Each transport is responsible for creating its own protocol specific listener, for example a servlet in the case of HTTP. This listener then passes whatever messages it receives to the channel via Channel.receive(MessageContext, InMessage). Channels simply delegate their receive() to a ChannelEndpoint which application specific handling of what to do with the message. The default endpoint is aptly named DefaultEndpoint and will be covered in the next section.

InMessage and OutMessage

MessageSerializer

Each OutMessage has a MessageSerializer. A message serializer takes the message body (message.getBody()) and writes it to an XMLStreamWriter that the Channel provides. The semantics of MessageSerializers should be such that they can be invoked multiple times.

Channels/Tr ansports without Services

Its important to note that Channels and transports are completely independent of XFire's Services. So I can use a channel to send a receive messages and never even create a service. I simply need to provide my own ChannelEndpoint.

DefaultEndpoint and the processing flow

DefaultEndpoint takes a message, creates a default message exchange called InMessageExchange and creates a message pipeline. The message pipeline at first consists of the global in handlers from XFire.getInHandlers() and the transport handlers from Transport.getInHandlers. Later on when the service is resolved, the service's handlers get added into the pipeline. Once the operation is resolved, if there is an out message to be set an Out pipeline is created and added to the MessageContext.

Phases and H andlers

See Processing Pipeline for now.

SOAP Processing

SOAPTransport.createTransport() adds SOAP support to a particular transport. It does so by adding three additional handlers:

  1. ReadHeaderHandler - this handler reads in the soap headers. It stops reading the XML stream the moment the whitespace stops after the Body tag. If it encounters a Fault in the Body, an XFireFault is thrown. [[1]] ValidateHeadersHandler - Ensure that all the necessary headers are understood by the receiving handlers. [[1]] SoapSerializerHandler - Services provide a MessageSerializer of their own which is responsible for serializing the soap body. But what about the message headers? This is written out by the SoapSerializer. What the SoapSerializerHandler does is replace the outMessage.MessageSerializer with new SoapSerializer(outM sg.getMessageSerializer()).

MessageExchanges

+
+
+
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/doxia-example-book/transports.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/doxia-example-book/transports.html (added) +++ websites/staging/maventest-doxia/trunk/content/doxia-example-book/transports.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,182 @@ + + + + + Transports + + + + + + + + + + + + +
+ +
+ +
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/extpaths.txt ============================================================================== --- websites/staging/maventest-doxia/trunk/content/extpaths.txt (added) +++ websites/staging/maventest-doxia/trunk/content/extpaths.txt Thu Mar 1 18:57:00 2012 @@ -0,0 +1 @@ +# extpaths for doxia \ No newline at end of file Added: websites/staging/maventest-doxia/trunk/content/faq.html ============================================================================== --- websites/staging/maventest-doxia/trunk/content/faq.html (added) +++ websites/staging/maventest-doxia/trunk/content/faq.html Thu Mar 1 18:57:00 2012 @@ -0,0 +1,322 @@ + + + + + Frequently Asked Questions + + + + + + + + + + + + +
+ +
+
+
+
How to handle style in the APT markup language?
+

+ APT does not support style. If you need more control you should use + xdoc instead. +

+

[top]


How to export in PDF?
+

+ There are two modules available that can be used to generate pdf output: an + iText module + that uses the + iText framework, and a + FO module, + that can be used e.g. in conjunction with + Apache FOP to generate a pdf. + Unfortunately, the iText team has discontinued the XML to PDF functionalities, so probably + only the fo module is going to be supported in the future. +

+

+ For Maven there is a pdf plugin available. +

+

[top]


Is it possible to create a book?
+

+ Doxia also has a fairly simple tool for writing books. It comes complete with a Maven plugin + to produce PDFs, LaTeX documents and Xdoc for direct integration in your Maven site. + The Doxia Book code + is still limited but fully functional. +

+

+ See Writing Books in Doxia for more information. +

+

[top]


Why XML based sinks don't generate nicely formatted documents?
+

+ We decided to keep pretty printing out of the core modules. So, XML based sinks like Xdoc or XHTML are + intentionally unformatted. You could always do this after the document generation or directly + by creating a specialized end-user sink (see DOXIA-255). +

+

[top]


Where are the Maven Doxia XSD schemas files?
+

+ The Doxia XSD files are located here: +

+ +
+
Xdoc XSD 2.0
+
http://maven.apache.org/xsd/xdoc-2.0.xsd
+
FML XSD 1.0.1
+
http://maven.apache.org/xsd/fml-1.0.1.xsd
+
Book XSD 1.0
+
http://maven.apache.org/xsd/book-1.0.0.xsd
+
Document XSD 1.0.1
+
http://maven.apache.org/xsd/document-1.0.1.xsd
+
Decoration XSD 1.0
+
http://maven.apache.org/xsd/decoration-1.0.0.xsd
+
+ +

+ Your favorite IDE probably supports XSD schema's for Xdoc and FML files. You need to + specify the following: +

+<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">
+  ...
+</document>
+
+<faqs xmlns="http://maven.apache.org/FML/1.0.1"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd">
+  ...
+</faqs>
+
+<book xmlns="http://maven.apache.org/BOOK/1.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/BOOK/1.0.0 http://maven.apache.org/xsd/book-1.0.0.xsd">
+  ...
+</book>
+
+<document xmlns="http://maven.apache.org/DOCUMENT/1.0.1"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/DOCUMENT/1.0.1 http://maven.apache.org/xsd/document-1.0.1.xsd"
+  outputName="...">
+  ...
+</document>
+
+<project xmlns="http://maven.apache.org/DECORATION/1.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd">
+  ...
+</project>
+ +

+ Note: for preformance reasons, all XSDs/DTDs use a cache in ${java.io.tmpdir}. +

+

[top]


How to define character entities in Doxia XML files with XSD?
+

+ Since it is not possible to define character entity references (like &copy;) in XSDs (unlike DTDs), each + XML file should have a <!DOCTYPE> to define the character entity set. +

+

+ For instance, you could add the following in your Xdoc XML files to be similar to XHTML 1.0 Transitional dtd: +

+<!DOCTYPE document [
+  <!-- These are the entity sets for ISO Latin 1 characters for the XHTML -->
+  <!ENTITY % HTMLlat1 PUBLIC "-//W3C//ENTITIES Latin 1 for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent">
+  %HTMLlat1;
+  <!-- These are the entity sets for special characters for the XHTML -->
+  <!ENTITY % HTMLsymbol PUBLIC "-//W3C//ENTITIES Symbols for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent">
+  %HTMLsymbol;
+  <!-- These are the entity sets for symbol characters for the XHTML -->
+  <!ENTITY % HTMLspecial PUBLIC "-//W3C//ENTITIES Special for XHTML//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent">
+  %HTMLspecial;
+]>
+<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">
+...
+</document>
+ +

+ Note: if CDATA is used to specify entity, Doxia will replace & by &amp; (i.e + "<![CDATA[&iexcl;]]>" becomes "&amp;iexcl;"). +

+

[top]


How to integrate Doxia 1.1 with Maven?
+

+ See this page. +

+

[top]

+
+
+
+
+
+ + + Added: websites/staging/maventest-doxia/trunk/content/images/apache-maven-project-2.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/apache-maven-project-2.png ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: websites/staging/maventest-doxia/trunk/content/images/architecture.odg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/architecture.odg ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: websites/staging/maventest-doxia/trunk/content/images/architecture.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/architecture.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/maventest-doxia/trunk/content/images/banner.jpg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/banner.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: websites/staging/maventest-doxia/trunk/content/images/bg.jpg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/bg.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: websites/staging/maventest-doxia/trunk/content/images/breadcrumbs.jpg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/breadcrumbs.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: websites/staging/maventest-doxia/trunk/content/images/collapsed.gif ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/collapsed.gif ------------------------------------------------------------------------------ svn:mime-type = image/gif Added: websites/staging/maventest-doxia/trunk/content/images/doxia-logo.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/doxia-logo.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/maventest-doxia/trunk/content/images/doxia-logo.svg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/doxia-logo.svg ------------------------------------------------------------------------------ svn:mime-type = image/svg+xml Added: websites/staging/maventest-doxia/trunk/content/images/expanded.gif ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/expanded.gif ------------------------------------------------------------------------------ svn:mime-type = image/gif Added: websites/staging/maventest-doxia/trunk/content/images/external.png ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/external.png ------------------------------------------------------------------------------ svn:mime-type = image/png Added: websites/staging/maventest-doxia/trunk/content/images/h3.jpg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/h3.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg Added: websites/staging/maventest-doxia/trunk/content/images/h5.jpg ============================================================================== Binary file - no diff available. Propchange: websites/staging/maventest-doxia/trunk/content/images/h5.jpg ------------------------------------------------------------------------------ svn:mime-type = image/jpeg