; Mon, 24 Jun 2013 17:11:18 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r867253 [31/46] - in /websites/production/cxf/content: ./ 2008/04/28/ 2008/06/20/ 2009/02/10/ 2009/08/04/ cache/ docs/ docs/cxf-architecture.thumbs/ docs/cxf-dependency-graphs.thumbs/ docs/logbrowser-configuration.thumbs/ docs/logbrowser-so... Date: Mon, 24 Jun 2013 17:10:57 -0000 To: commits@cxf.apache.org From: dkulp@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20130624171118.CC5DB2388C91@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: websites/production/cxf/content/docs/jaxrs-services-description.html ============================================================================== --- websites/production/cxf/content/docs/jaxrs-services-description.html (original) +++ websites/production/cxf/content/docs/jaxrs-services-description.html Mon Jun 24 17:10:51 2013 @@ -25,6 +25,18 @@ + + + + + + + + + Apache CXF -- JAXRS Services Description @@ -42,19 +54,15 @@ Apache CXF -- JAXRS Services Description -

- +

@@ -94,7 +102,7 @@ Apache CXF -- JAXRS Services Description

Search +

@@ -139,43 +147,43 @@ RESTful Web applications. Please check t

A top level WADL document element is called "application". Usually it may contain a "grammars" section and "resources" element with one or more top-level "resource" elements, with each one representing a specific root resource, for example:

-<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
- <grammars>
-  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
-        xmlns:tns="http://superbooks" attributeFormDefault="unqualified" elementFormDefault="unqualified" 
-        targetNamespace="http://superbooks">
-    <xs:element name="thebook" type="tns:book"/>
-    <xs:complexType name="book">
-        <xs:sequence>
-            <xs:element minOccurs="0" ref="tns:thechapter"/>
-            <xs:element name="id" type="xs:int"/>
-        </xs:sequence>
-    </xs:complexType>
-  </xs:schema>
- </grammars>
- <resources base="http://localhost:8080/">
-   <resource path="/bookstore/{id}">
-     <param name="id" style="template"/>
-     <method name="GET">
-      <response>
-       <representation mediaType="application/xml" element="ns:thebook"/>
-      </response>
-    </method>
-   </resource>
-   <resource path="/books">
-      <resource path="/bookstore/{id}">
-        <param name="id" style="template"/>
-        <method name="GET">
-          <response>
-           <representation mediaType="application/xml" element="ns:thebook"/>
-          </response>
-        </method>
-      </resource>
-   </resource>
- </resources>  
-</application>
-

This document describes an application that has "http://localhost:8080/" base URI. It can handle GET requests such as
@@ -199,34 +207,34 @@ RESTful Web applications. Please check t

Note that inlined schemas can be included instead by referencing external schemas. Likewise, most of WADL element declarations such as "resource", "method", "representation", etc can be shared by using the same document or external references. Here is how the basic example can be simplified with the help of references:

-<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
- <grammars>
-   <include href="schemas/book.xsd"/>
- </grammars>
-
- <resource_type id="bookResource">
-     <param name="id" style="template"/>
-     <method name="GET">
-       <response>
-        <representation mediaType="application/xml" element="ns:thebook"/>
-       </response>
-    </method>
- </resource_type>
-
- <resources base="http://localhost:8080/">
-   <resource path="/bookstore/{id}" type="#bookResource"/>
-   <resource path="/books">
-      <resource path="/bookstore/{id}" type="#bookResource"/>
+

Note that a book.xsd schema resource located in the 'schemas' path relative to the location of this WADL document is referenced using wadl:include element. Abstract resource type "bookResource" is declared as an immediate child of wadl:application and is linked to concrete resource elements using a "#bookResource" reference.

@@ -238,38 +246,38 @@ RESTful Web applications. Please check t

For example, the following baseApplication.wadl documents describes an abstract "bookResource" resource:

-<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
- <grammars>
-   <include href="schemas/book.xsd"/>
- </grammars>
-
- <resource_type id="bookResource">
-     <param name="id" style="template"/>
-     <method name="GET">
-       <response>
-        <representation mediaType="application/xml" element="ns:thebook"/>
-       </response>
-    </method>
- </resource_type>
-</application>
-

and this WADL document links to the abstract resource by using an external WADL reference with a "baseResource" fragment.

-<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
+

@@ -285,23 +293,23 @@ RESTful Web applications. Please check t

Code generator expects WADL resource and method elements to have "id" attributes set which can provide hints on how to name generated classes and methods. For example:

-<application xmlns="http://wadl.dev.java.net/2009/02" xmlns:ns="http://superbooks">
- <grammars>
-  <include href="schemas/book.xsd"/>
- </grammars>
- <resources base="http://localhost:8080/">
-   <resource path="/bookstore/{id}" id="org.apache.cxf.jaxrs.systest.BookStore">
-     <param name="id" style="template"/>
-     <method name="GET" id="getBook">
-      <response>
-       <representation mediaType="application/xml" element="ns:thebook"/>
-      </response>
-    </method>
-   </resource>
- </resources>  
-</application>
-

Note that resource id is "org.apache.cxf.jaxrs.systest.BookStore". Alternatively, expanded QName can be used as "id":
@@ -352,15 +360,15 @@ Alternatively, in combination with a '-n

At the moment it is possible to apply external JAXB customizations to WADL grammars however it is not possible yet to restrict a given customization to a specific WADL document or explicitly inlined schema. Linking binding to external schemas works, for example, the following bindings file can be used:

-<jaxb:bindings version="2.0"
-	xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
-	xmlns:xs="http://www.w3.org/2001/XMLSchema"
-	schemaLocation="schemas/book.xsd"
-	node="//xs:complexType[@name='book2']/xs:sequence/xs:element[@name='id']">
-	<jaxb:property name="book2Id"/>
-</jaxb:bindings>
-

wadl2java Maven plugin

@@ -368,51 +376,51 @@ Alternatively, in combination with a '-n

If you need the code generated during Maven build then the following plugin can be used:

-<groupId>org.apache.cxf</groupId>
-<artifactId>cxf-wadl2java-plugin</artifactId>
-<version>2.4.1</version>
-

Add this plugin to the build section of your project's pom and specify a 'wadl2java' goal, for example:

-<build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.cxf</groupId>
-                <artifactId>cxf-wadl2java-plugin</artifactId>
-                <version>2.4.1</version>
-                <executions>
-                    <execution>
-                        <id>generate-sources</id>
-                        <phase>generate-sources</phase>
-                        <configuration>
-                            <sourceRoot>${basedir}/target/generated/src/main/java</sourceRoot>
-                            <wadlOptions>
-                                <wadlOption>
-                                    <wadl>${basedir}/src/test/resources/wadl/bookstoreImport.xml</wadl>
-                                    <impl>true</impl>
+

Note that the minimum and maximum memory limits may need to be increased when using the plugin to process large WADL documents, for example, add "-Xms512M -Xmx1024M" to the list of Maven options.

@@ -420,17 +428,17 @@ Alternatively, in combination with a '-n

CXF will generate artifacts in the <sourceRoot> directory. Configuration arguments which are included inside the <wadlOption> element are used to pass arguments to the tooling and correspond to the options outlined in the wadltojava section, they can be specified explicitly, as above, or using an "extraargs" wrapper, for example:

-<wadlOptions>
-	<wadlOption>
-		<wadl>$\{basedir}/src/main/wadl/bookStore.wadl</wsdl>
-                <extraargs>
-                    <extraarg>-impl</extraarg>
-                    <extraarg>-verbose</extraarg>
-                </extraargs>
-	</wadlOption>
-</wadlOptions>
-

Integration

@@ -441,11 +449,11 @@ First option is to pass the collected op

Another approach is to use org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainer class shipped with the cxf-tools-wadlto-jaxrs module:

-<groupId>org.apache.cxf</groupId>
-<artifactId>cxf-tools-wadlto-jaxrs</artifactId>
-<version>2.4.1</version>
-

Please see CXF source for more details and org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainerTest in particular.

@@ -454,13 +462,13 @@ First option is to pass the collected op

External WADL documents can be linked to from jaxrs:server endpoints using newly introduced "docLocation" attribute, for example:

-<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl">
-   <jaxrs:serviceBeans>
-      <bean class="org.bar.generated.BookStore"/> 
-   </jaxrs:serviceBeans>
-</jaxrs:server>
-

If external WADL documents include external schemas and jaxrs endpoints need to have the schema validation enabled, then those schemas can be referenced in the jaxrs:schemaLocations section as well.

@@ -481,33 +489,33 @@ Note that JAX-RS subresources are late-r

Note that starting from CXF 2.4.0, Description annotations can be applied to input parameters. Additionally, a method-level Descriptions annotation can have a collection of categorized Description annotations, with each Description targeting a specific WADL element by setting its 'target' property to one of the DocTarget values. For example, one can use a Descriptions annotation to document the response representation of a particular resource method, as well as add documentation fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response elements:

Every unique @Path value adds a new 'resource' element to the generated WADL, thus the last Description annotation in the @Descriptions array ensures the doc extension is also added to the 'resource' element. Note that multiple resource methods having different HTTP methods but sharing the same @Path value will have the same parent 'resource' element representing this shared path fragment, in this case a Description with the DocTarget.RESOURCE target will be ignored unless it is added to the first resource method with this shared @Path:

@@ -531,13 +539,13 @@ org.apache.cxf.jaxrs.model.wadl.WadlGene

Starting from CXF 2.5.5 and 2.6.2 it is possible to get explicit collections represented in generated WADL grammar sections and have WADL representations linking to these schema elements. Note it is only possible for JAXB collections, for example:

Given the above example, WADLGenerator will attempt to add a 'books' element to the generated schema with the targetNamespace set to "http://books". This 'books' element will have a sequence of elements linking to a type representing the "Book" class.

@@ -548,10 +556,10 @@ org.apache.cxf.jaxrs.model.wadl.WadlGene

Even when you do use JAXB, the JAXB types may have been generated from the external schema so having WadlGenerator attempting to recreate the original schema may not work well. To have a generated WADL referencing the original schema(s) please set a 'schemaLocations' list property (programmatically or from Spring) :

-WadlGenerator wg = new WadlGenerator();
-wg.setSchemaLocations(Collections.singletonList("classpath:/book.xsd"));
-

In this case the grammar section will have the 'book.xsd' schema inlined. If this schema imports other schemas then the imports with relative URIs will be replaced by the absolute URIs based on the current endpoint's base address. For example, if the endpoint address is "http://somehost/bar" and the 'book.xsd' imports "foo/book1.xsd" then the published WADL will contain an "http://somehost/bar/foo/book1.xsd". At the moment a custom RequestHandler filter will have to be registered to serve resources such as "http://somehost/bar/foo/book1.xsd" which can 'calculate' which resource is required get the absolute request URI and comparing it with the base URI, possibly with the help of the injected JAXRS UriInfo context. Alternatively, resources such as book1.xsd may be served by CXFServlet itself (see the Redirection with CXFServlet)

@@ -560,24 +568,24 @@ wg.setSchemaLocations(Collections.single

Note that the root schema such as "book.xsd" is inlined - you can have it referenced only by setting an 'externalLinks' list property. This will work very well when the "book.xsd" is indeed available at the external URI, but this property can also be used to avoid the local schemas being inlined. Moreover, the use of JAXB will not be required. The result will look like this:

-<wadl:grammars>
-<wadl:include href="http://books.xsd"/>
-</wadl:grammars>
-

Note that "schemaLocations" and "externalLinks" properties differ in that the schemas referenced by the former one are inlined.

You can also customize the way schema elements are referenced. When WadlGenerator creates WADL representation elements (representing resource method input or output types) it will be able to link to schema elements provided a given type is actually a JAXB one, so the result may look like this :

If no JAXB is used then you can attach an XMLName annotation to method input or output types. Alternatively, you can register an instance of ElementQNameResolver with the WadlGenerator which will be used for creating wadl:representation/@element values.

@@ -594,12 +602,12 @@ WADLGenerator can be indirectly configur

For example, given

and visiting

@@ -624,14 +632,14 @@ with a given jaxrs:server endpoint.

For example, if the following 2 root resource classes has been registered with this endpoint:

-@Path("/fiction") 
-public class FictionBookOrders {
+

then WADL will contain the description of both FictionBookOrders and SportBookOrders resources.

Modified: websites/production/cxf/content/docs/jaxrs-testing.html ============================================================================== --- websites/production/cxf/content/docs/jaxrs-testing.html (original) +++ websites/production/cxf/content/docs/jaxrs-testing.html Mon Jun 24 17:10:51 2013 @@ -25,6 +25,17 @@ + + + + + + + + Apache CXF -- JAXRS Testing @@ -42,19 +53,15 @@ Apache CXF -- JAXRS Testing

- +

@@ -94,7 +101,7 @@ Apache CXF -- JAXRS Testing

Search +

@@ -132,88 +139,88 @@ Apache CXF -- JAXRS Testing

Embedded Jetty

-import javax.ws.rs.core.Response;
+

It is quite easy to setup a server and start testing it. The advantage of using the embedded Jetty is that a complete end-to-end round-trip can be exercised, thus stressing all the CXF runtime which comes at the cost of some added complexity to do with setting up the server.

@@ -225,72 +232,72 @@ This avoids the need to start an embedde

Note that setting a LocalConduit.DIRECT_DISPATCH property to 'true' ensures that the invocation goes immediately into the service chain after the client out chain has completed. This works well for all HTTP verbs including GET, POST, etc.

Modified: websites/production/cxf/content/docs/jetty-configuration.html ============================================================================== --- websites/production/cxf/content/docs/jetty-configuration.html (original) +++ websites/production/cxf/content/docs/jetty-configuration.html Mon Jun 24 17:10:51 2013 @@ -25,6 +25,18 @@ + + + + + + + + + Apache CXF -- Jetty Configuration @@ -42,19 +54,15 @@ Apache CXF -- Jetty Configuration

- +

@@ -94,7 +102,7 @@ Apache CXF -- Jetty Configuration

Search +

@@ -132,15 +140,15 @@ Apache CXF -- Jetty Configuration

The elements used to configure the Jetty runtime are defined in the namespace http://cxf.apache.org/transports/http-jetty/configuration. It is commonly referred to using the prefix httpj. In order to use the Jetty configuration elements you will need to add the lines shown below to the beans element of your endpoint's configuration file. In addition, you will need to add the configuration elements' namespace to the xsi:schemaLocation attribute.

The `engine-factory` element

@@ -182,14 +190,14 @@ The threadingParameters has two

The example below shows a configuration fragment that configures a Jetty instance on port number 9001.

-<beans xmlns="http://www.springframework.org/schema/beans"
-  xmlns:beans="http://www.springframework.org/schema/beans"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-  xmlns:sec="http://cxf.apache.org/configuration/security"
-  xmlns:http="http://cxf.apache.org/transports/http/configuration"
-  xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration"
-  xmlns:jaxws="http://java.sun.com/xml/ns/jaxws"
+

Modified: websites/production/cxf/content/docs/jms-transport.html ============================================================================== --- websites/production/cxf/content/docs/jms-transport.html (original) +++ websites/production/cxf/content/docs/jms-transport.html Mon Jun 24 17:10:51 2013 @@ -25,6 +25,17 @@ + + + + + + + + Apache CXF -- JMS Transport @@ -42,19 +53,15 @@ Apache CXF -- JMS Transport

- +

@@ -94,7 +101,7 @@ Apache CXF -- JMS Transport

Search +

@@ -133,18 +140,18 @@ Apache CXF -- JMS Transport

The WSDL extensions for defining a JMS endpoint are defined in the namespace http://cxf.apache.org/transports/jms. In order to use the JMS extensions you will need to add the namespace definition shown below to the definitions element of your contract.

JMS Extension Namespace

-xmlns:jms="http://cxf.apache.org/transports/jms"
-

Configuration Namespaces

In order to use the JMS configuration properties you will need to add the line shown below to the beans element of your configuration.

JMS Configuration Namespaces

-xmlns:jms="http://cxf.apache.org/transports/jms"
-

Basic Endpoint Configuration

@@ -182,19 +189,19 @@ The following is a list of common JNDI p

The following example shows an example of a JMS WSDL port specification.

JMS WSDL Port Specification

-<service name="JMSService">
-  <port binding="tns:Greeter_SOAPBinding" name="SoapPort">
-    <jms:address jndiConnectionFactoryName="ConnectionFactory"
-                 jndiDestinationName="dynamicQueues/test.cxf.jmstransport">
-      <jms:JMSNamingProperty name="java.naming.factory.initial"
-                             value="org.apache.activemq.jndi.ActiveMQInitialContextFactory" />
-      <jms:JMSNamingProperty name="java.naming.provider.url"
-                             value="tcp://localhost:61616" />
-    </jms:address>
+

Using Configuration

@@ -224,33 +231,33 @@ The following is a list of common JNDI p

Example

Addressing Information a Configuration File

-<beans xmlns="http://www.springframework.org/schema/beans"
-       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xmlns:ct="http://cxf.apache.org/configuration/types"
-       xmlns:jms="http://cxf.apache.org/transports/jms"
-       xsi:schemaLocation="
-           http://www.springframework.org/schema/beans 
-           http://www.springframework.org/schema/beans/spring-beans.xsd
-           http://cxf.apache.org/jaxws
-           http://cxf.apache.org/schemas/jaxws.xsd
-           http://cxf.apache.org/transports/jms
-           http://cxf.apache.org/schemas/configuration/jms.xsd">
-<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
-  <jms:address destinationStyle="queue"
-               jndiConnectionFactoryName="myConnectionFactory"
-               jndiDestinationName="myDestination"
-               jndiReplyDestinationName="myReplyDestination"
-               connectionUserName="testUser"
-               connectionPassword="testPassword">
-    <jms:JMSNamingProperty name="java.naming.factory.initial"
-         value="org.apache.cxf.transport.jms.MyInitialContextFactory"/>
-    <jms:JMSNamingProperty name="java.naming.provider.url"
-         value="tcp://localhost:61616"/>
-  </jms:address>
+

Consumer Endpoint Configuration

@@ -274,29 +281,29 @@ The following is a list of common JNDI p

The following example shows a configuration entry for configuring a JMS consumer endpoint.

Configuration for a JMS Consumer Endpoint

-<beans xmlns="http://www.springframework.org/schema/beans"
-       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xmlns:ct="http://cxf.apache.org/configuration/types"
-       xmlns:jms="http://cxf.apache.org/transports/jms"
-       xsi:schemaLocation="
-           http://www.springframework.org/schema/beans 
-           http://www.springframework.org/schema/beans/spring-beans.xsd"
-           http://cxf.apache.org/jaxws
-           http://cxf.apache.org/schemas/jaxws.xsd
-           http://cxf.apache.org/transports/jms
-           http://cxf.apache.org/schemas/configuration/jms.xsd">
-...
-<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
-  <jms:address ... >
+

The id on the jms:conduit is in the form of {WSDLNamespace}WSDLPortName.jms-conduit. This provides CXF with the information so that it can associate the configuration with your service's endpoint.

@@ -329,33 +336,33 @@ The following is a list of common JNDI p

The following example shows a CXF configuration entry for configuring a JMS service endpoint.

Configuration for a JMS Service Endpoint

-<beans xmlns="http://www.springframework.org/schema/beans"
-       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-       xmlns:ct="http://cxf.apache.org/configuration/types"
-       xmlns:jms="http://cxf.apache.org/transports/jms"
-       xsi:schemaLocation="
-           http://www.springframework.org/schema/beans
-           http://www.springframework.org/schema/beans/spring-beans.xsd"
-           http://cxf.apache.org/jaxws
-           http://cxf.apache.org/schemas/jaxws.xsd
-           http://cxf.apache.org/transports/jms
-           http://cxf.apache.org/schemas/configuration/jms.xsd">
-...
-<jms:destination name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-destination">
-  <jms:address ... >
+

Using WSDL

@@ -383,13 +390,13 @@ The jms:sessionPool element's a

The following example shows an example of configuring the session pool for a CXF JMS service endpoint.

JMS Session Pool Configuration

The jms:sessionPool element can also be used within a jms:conduit.

@@ -406,13 +413,13 @@ The jms:sessionPool element's a

The following example shows a configuration fragment that sets the consumer endpoint's request lifetime to 500 milliseconds and its timeout value to 500 milliseconds.

JMS Consumer Endpoint Runtime Configuration

-<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
-...
-  <jms:clientConfig clientReceiveTimeout="500"
-                    messageTimeToLive="500" />
+

Service Specific Runtime Configuration

@@ -428,15 +435,15 @@ The jms:sessionPool element's a

The following example shows a configuration fragment that sets the service endpoint's response lifetime to 500 milliseconds and its durable subscription client identifier to jms-test-id.

JMS Service Endpoint Runtime Configuration

-<jms:destination id="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-destination">
-  <jms:address ... >
+

wadl2java Maven plugin

Integration

Embedded Jetty

The engine-factory element

Configuration Namespaces

Basic Endpoint Configuration

Using Configuration

Example

Consumer Endpoint Configuration

Using WSDL

Service Specific Runtime Configuration

The `engine-factory` element