JBossWS SVN: r13207 - framework/trunk/src/main/java/org/jboss/wsf/framework/serviceref.
by jbossws-commits＠lists.jboss.org
Author: richard.opalka(a)jboss.com
Date: 2010-11-03 04:16:41 -0400 (Wed, 03 Nov 2010)
New Revision: 13207
Modified:
framework/trunk/src/main/java/org/jboss/wsf/framework/serviceref/DefaultServiceRefHandler.java
Log:
[JBWS-3152] refactoring
Modified: framework/trunk/src/main/java/org/jboss/wsf/framework/serviceref/DefaultServiceRefHandler.java
===================================================================
--- framework/trunk/src/main/java/org/jboss/wsf/framework/serviceref/DefaultServiceRefHandler.java 2010-11-03 08:11:40 UTC (rev 13206)
+++ framework/trunk/src/main/java/org/jboss/wsf/framework/serviceref/DefaultServiceRefHandler.java 2010-11-03 08:16:41 UTC (rev 13207)
@@ -21,85 +21,47 @@
*/
package org.jboss.wsf.framework.serviceref;
-import javax.naming.Context;
-import javax.naming.NamingException;
import javax.naming.Referenceable;
import org.jboss.wsf.spi.SPIProvider;
import org.jboss.wsf.spi.SPIProviderResolver;
-import org.jboss.wsf.spi.deployment.UnifiedVirtualFile;
import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
import org.jboss.wsf.spi.serviceref.ServiceRefBinder;
import org.jboss.wsf.spi.serviceref.ServiceRefBinderFactory;
import org.jboss.wsf.spi.serviceref.ServiceRefHandler;
-import org.jboss.wsf.spi.serviceref.ServiceRefMetaData;
/**
- * Bind service refs in the client's ENC
- * for every service-ref element in the deployment descriptor.
+ * Binds service refs to the client's ENC.
*
- * @author Thomas.Diesler(a)jboss.org
- * @author Heiko.Braun(a)jboss.com
* @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
- * @since 04-Nov-2006
*/
-public class DefaultServiceRefHandler implements ServiceRefHandler
+public final class DefaultServiceRefHandler implements ServiceRefHandler
{
@Override
- @Deprecated
- public void bindServiceRef(final Context encCtx, final String encName, final UnifiedVirtualFile ignored,
- final ClassLoader loader, final ServiceRefMetaData serviceRefMD) throws NamingException
+ public Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRefMD)
{
- final UnifiedServiceRefMetaData serviceRefUMDM = (UnifiedServiceRefMetaData) serviceRefMD;
- final Type bindingType = getServiceRefType(serviceRefUMDM, loader);
+ if (serviceRefMD.getVfsRoot() == null)
+ {
+ throw new IllegalStateException("VFSRoot must be provided");
+ }
+ final Type type = this.getServiceRefType(serviceRefMD);
- this.getBinder(bindingType).setupServiceRef(encCtx, encName, null, serviceRefUMDM, loader);
+ return this.getBinder(type).createReferenceable(serviceRefMD);
}
-
- @Override
- public Referenceable createReferenceable(UnifiedServiceRefMetaData serviceRef, ClassLoader loader)
+ private Type getServiceRefType(final UnifiedServiceRefMetaData serviceRefMD)
{
- final Type bindingType = getServiceRefType(serviceRef, loader);
+ final boolean isJAXRPC = serviceRefMD.getMappingFile() != null
+ || "javax.xml.rpc.Service".equals(serviceRefMD.getServiceInterface());
- return this.getBinder(bindingType).createReferenceable(serviceRef, loader);
+ return isJAXRPC ? Type.JAXRPC : Type.JAXWS;
}
- private ServiceRefBinder getBinder(final Type binderType)
+ private ServiceRefBinder getBinder(final Type type)
{
final SPIProvider spiProvider = SPIProviderResolver.getInstance().getProvider();
final ServiceRefBinderFactory serviceRefBindingFactory = spiProvider.getSPI(ServiceRefBinderFactory.class);
- return serviceRefBindingFactory.newServiceRefBinder(binderType);
+ return serviceRefBindingFactory.newServiceRefBinder(type);
}
-
- private Type getServiceRefType(final UnifiedServiceRefMetaData serviceRef, final ClassLoader loader)
- {
- // Both service-ref-type and annotated element are JAXWS specific
- if (serviceRef.getServiceRefType() != null || serviceRef.getAnnotatedElement() != null)
- return Type.JAXWS;
-
- // The mapping-file is JAXRPC specific
- if (serviceRef.getMappingFile() != null)
- return Type.JAXRPC;
-
- final String serviceInterfaceName = serviceRef.getServiceInterface();
- if (serviceInterfaceName == null)
- throw new IllegalStateException("<service-interface> cannot be null");
-
- try
- {
- final Class<?> siClass = loader.loadClass(serviceInterfaceName);
- if (javax.xml.ws.Service.class.isAssignableFrom(siClass))
- return Type.JAXWS;
- else if (javax.xml.rpc.Service.class.isAssignableFrom(siClass))
- return Type.JAXRPC;
- else
- throw new IllegalStateException("Illegal service interface: " + serviceInterfaceName);
- }
- catch (ClassNotFoundException e)
- {
- throw new IllegalStateException("Cannot load <service-interface>: " + serviceInterfaceName);
- }
- }
}
14 years, 4 months
- 1
- 0
JBossWS SVN: r13206 - common/trunk/src/main/java/org/jboss/wsf/common/serviceref.
by jbossws-commits＠lists.jboss.org
Author: richard.opalka(a)jboss.com
Date: 2010-11-03 04:11:40 -0400 (Wed, 03 Nov 2010)
New Revision: 13206
Removed:
common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinder.java
common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXRPC.java
common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXWS.java
Modified:
common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceObjectFactoryJAXWS.java
Log:
[JBWS-3152] refactoring - moving JBossWS service-ref MD setup code from JBossWS to AS MD
Modified: common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceObjectFactoryJAXWS.java
===================================================================
--- common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceObjectFactoryJAXWS.java 2010-11-03 08:05:39 UTC (rev 13205)
+++ common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceObjectFactoryJAXWS.java 2010-11-03 08:11:40 UTC (rev 13206)
@@ -24,6 +24,7 @@
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
+import java.net.MalformedURLException;
import java.net.URL;
import java.util.Collection;
import java.util.Hashtable;
@@ -37,6 +38,8 @@
import javax.xml.namespace.QName;
import javax.xml.ws.RespectBindingFeature;
import javax.xml.ws.Service;
+import javax.xml.ws.WebServiceClient;
+import javax.xml.ws.WebServiceException;
import javax.xml.ws.WebServiceFeature;
import javax.xml.ws.soap.AddressingFeature;
import javax.xml.ws.soap.MTOMFeature;
@@ -98,7 +101,7 @@
this.configure(serviceRef, serviceInstance);
// construct port
- final boolean instantiatePort = targetClassName != null && !targetClassName.equals(serviceImplClass);
+ final boolean instantiatePort = targetClassName != null && !Service.class.isAssignableFrom(targetClass);
if (instantiatePort)
{
final QName portQName = this.getPortQName(targetClassName, serviceImplClass, serviceRef);
@@ -158,20 +161,18 @@
private String getServiceClassName(final UnifiedServiceRefMetaData serviceRefMD)
{
- return serviceRefMD.getServiceImplClass();
+ final String serviceImplClassName = serviceRefMD.getServiceImplClass();
+ if (serviceImplClassName != null) return serviceImplClassName;
+
+ final String serviceInterfaceName = serviceRefMD.getServiceInterface();
+ if (serviceInterfaceName != null) return serviceInterfaceName;
+
+ return Service.class.getName(); // fallback
}
private String getTargetClassName(final UnifiedServiceRefMetaData serviceRefMD)
{
- String targetClassName = serviceRefMD.getServiceRefType();
-
- if (targetClassName == null)
- targetClassName = serviceRefMD.getServiceInterface();
-
- if (Service.class.getName().equals(targetClassName))
- targetClassName = serviceRefMD.getServiceImplClass();
-
- return targetClassName;
+ return serviceRefMD.getServiceRefType();
}
private Object instantiatePort(final Class<?> serviceClass, final Class<?> targetClass, final Service target,
@@ -211,8 +212,8 @@
throws NoSuchMethodException, InstantiationException, IllegalAccessException, InvocationTargetException
{
final WebServiceFeature[] features = getFeatures(serviceRefMD);
- final URL wsdlURL = serviceRefMD.getWsdlLocation();
- final QName serviceQName = serviceRefMD.getServiceQName();
+ final URL wsdlURL = this.getWsdlURL(serviceRefMD, serviceClass);
+ final QName serviceQName = this.getServiceQName(serviceRefMD, serviceClass);
Service target = null;
if (serviceClass == Service.class)
@@ -274,6 +275,40 @@
return target;
}
+ private URL getWsdlURL(final UnifiedServiceRefMetaData serviceRefMD, final Class<?> serviceClass)
+ {
+ if (serviceRefMD.getWsdlLocation() == null)
+ {
+ final WebServiceClient webServiceClientAnnotation = serviceClass.getAnnotation(WebServiceClient.class);
+ if (webServiceClientAnnotation != null)
+ {
+ // use the @WebServiceClien(wsdlLocation=...) if the service ref wsdl location returned at this time would be null
+ if (webServiceClientAnnotation.wsdlLocation().length() > 0)
+ {
+ serviceRefMD.setWsdlOverride(webServiceClientAnnotation.wsdlLocation());
+ }
+ }
+ }
+
+ return serviceRefMD.getWsdlLocation();
+ }
+
+ private QName getServiceQName(final UnifiedServiceRefMetaData serviceRefMD, final Class<?> serviceClass)
+ {
+ QName retVal = serviceRefMD.getServiceQName();
+
+ if (retVal == null)
+ {
+ final WebServiceClient webServiceClientAnnotation = serviceClass.getAnnotation(WebServiceClient.class);
+ if (webServiceClientAnnotation != null)
+ {
+ retVal = new QName(webServiceClientAnnotation.targetNamespace(), webServiceClientAnnotation.name());
+ }
+ }
+
+ return retVal;
+ }
+
private WebServiceFeature[] getFeatures(final String targetClassName, final String serviceClassName,
final UnifiedServiceRefMetaData serviceRefMD)
{
Deleted: common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinder.java
===================================================================
--- common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinder.java 2010-11-03 08:05:39 UTC (rev 13205)
+++ common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinder.java 2010-11-03 08:11:40 UTC (rev 13206)
@@ -1,64 +0,0 @@
-/*
- * JBoss, Home of Professional Open Source.
- * Copyright 2010, Red Hat Middleware LLC, and individual contributors
- * as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors.
- *
- * This is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this software; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
- */
-
-package org.jboss.wsf.common.serviceref;
-
-import java.lang.reflect.AnnotatedElement;
-
-import javax.naming.Context;
-import javax.naming.NamingException;
-import javax.naming.Referenceable;
-
-import org.jboss.logging.Logger;
-import org.jboss.util.naming.Util;
-import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
-import org.jboss.wsf.spi.serviceref.ServiceRefBinder;
-
-/**
- * Abstract service ref binder.
- *
- * @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
- */
-abstract class AbstractServiceRefBinder implements ServiceRefBinder
-{
- private static final Logger log = Logger.getLogger(AbstractServiceRefBinder.class);
-
- @Deprecated
- public final void setupServiceRef(final Context encCtx, final String encName, final AnnotatedElement ignored,
- final UnifiedServiceRefMetaData serviceRef, final ClassLoader loader) throws NamingException
- {
- final Referenceable jndiReferenceable = this.createReferenceable(serviceRef, loader);
- this.bind(encCtx, encName, jndiReferenceable);
- }
-
- public abstract Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRef,
- final ClassLoader loader);
-
- private void bind(final Context encCtx, final String encName, final Referenceable jndiReferenceable)
- throws NamingException
- {
- final String jndiFullName = encCtx.getNameInNamespace() + "/" + encName;
-
- log.info("Binding service reference to [jndi=" + jndiFullName + "]");
- Util.bind(encCtx, encName, jndiReferenceable);
- }
-}
Deleted: common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXRPC.java
===================================================================
--- common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXRPC.java 2010-11-03 08:05:39 UTC (rev 13205)
+++ common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXRPC.java 2010-11-03 08:11:40 UTC (rev 13206)
@@ -1,47 +0,0 @@
-/*
- * JBoss, Home of Professional Open Source.
- * Copyright 2010, Red Hat Middleware LLC, and individual contributors
- * as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors.
- *
- * This is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this software; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
- */
-package org.jboss.wsf.common.serviceref;
-
-import javax.naming.Referenceable;
-
-import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
-
-/**
- * Binds a JAXRPC service object factory to the client's ENC.
- *
- * @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
- */
-public abstract class AbstractServiceRefBinderJAXRPC extends AbstractServiceRefBinder
-{
- public final Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRef, final ClassLoader ignored)
- {
- return this.createJAXRPCReferenceable(serviceRef);
- }
-
- /**
- * Template method for creating stack specific JAXRPC referenceables.
- *
- * @param serviceRef service reference UMDM
- * @return stack specific JAXRPC JNDI referenceable
- */
- protected abstract Referenceable createJAXRPCReferenceable(final UnifiedServiceRefMetaData serviceRef);
-}
Deleted: common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXWS.java
===================================================================
--- common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXWS.java 2010-11-03 08:05:39 UTC (rev 13205)
+++ common/trunk/src/main/java/org/jboss/wsf/common/serviceref/AbstractServiceRefBinderJAXWS.java 2010-11-03 08:11:40 UTC (rev 13206)
@@ -1,301 +0,0 @@
-/*
- * JBoss, Home of Professional Open Source.
- * Copyright 2010, Red Hat Middleware LLC, and individual contributors
- * as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors.
- *
- * This is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this software; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
- */
-package org.jboss.wsf.common.serviceref;
-
-import java.lang.annotation.Annotation;
-import java.lang.reflect.AnnotatedElement;
-import java.lang.reflect.Field;
-import java.lang.reflect.Method;
-import java.net.MalformedURLException;
-import java.net.URL;
-import java.util.ArrayList;
-import java.util.List;
-
-import javax.jws.HandlerChain;
-import javax.naming.Referenceable;
-import javax.xml.namespace.QName;
-import javax.xml.ws.RespectBinding;
-import javax.xml.ws.Service;
-import javax.xml.ws.WebServiceClient;
-import javax.xml.ws.WebServiceRef;
-import javax.xml.ws.WebServiceRefs;
-import javax.xml.ws.soap.Addressing;
-import javax.xml.ws.soap.MTOM;
-
-import org.jboss.wsf.spi.WSFException;
-import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
-
-/**
- * Binds a JAXWS service object factory to the client's ENC.
- *
- * @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
- */
-public abstract class AbstractServiceRefBinderJAXWS extends AbstractServiceRefBinder
-{
- public final Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRef, final ClassLoader loader)
- {
- this.processAddressingAnnotation(serviceRef);
- this.processMTOMAnnotation(serviceRef);
- this.processRespectBindingAnnotation(serviceRef);
- this.processHandlerChainAnnotation(serviceRef);
-
- final Class<?> targetClass = getTargetClass(serviceRef);
- final String targetClassName = (targetClass != null ? targetClass.getName() : null);
- final String serviceImplClassName = getServiceImplClassName(serviceRef);
-
- // TODO: investigate why these if conditions
- if (targetClassName != null)
- {
- serviceRef.setServiceInterface(targetClassName);
- }
- if (serviceRef.getServiceImplClass() == null)
- {
- serviceRef.setServiceImplClass(serviceImplClassName);
- }
-
- this.processWsdlOverride(serviceRef, loader);
-
- return this.createJAXWSReferenceable(serviceRef);
- }
-
- /**
- * Template method for creating stack specific JAXWS referenceables.
- *
- * @param serviceImplClass service implementation class name
- * @param targetClassName target class name
- * @param serviceRef service reference UMDM
- * @return stack specific JAXWS JNDI referenceable
- */
- protected abstract Referenceable createJAXWSReferenceable(final UnifiedServiceRefMetaData serviceRefMD);
-
- private void processAddressingAnnotation(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final Addressing addressingAnnotation = this.getAnnotation(serviceRefMD, Addressing.class);
-
- if (addressingAnnotation != null)
- {
- serviceRefMD.setAddressingEnabled(addressingAnnotation.enabled());
- serviceRefMD.setAddressingRequired(addressingAnnotation.required());
- serviceRefMD.setAddressingResponses(addressingAnnotation.responses().toString());
- }
- }
-
- private void processMTOMAnnotation(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final MTOM mtomAnnotation = this.getAnnotation(serviceRefMD, MTOM.class);
-
- if (mtomAnnotation != null)
- {
- serviceRefMD.setMtomEnabled(mtomAnnotation.enabled());
- serviceRefMD.setMtomThreshold(mtomAnnotation.threshold());
- }
- }
-
- private void processRespectBindingAnnotation(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final RespectBinding respectBindingAnnotation = this.getAnnotation(serviceRefMD, RespectBinding.class);
-
- if (respectBindingAnnotation != null)
- {
- serviceRefMD.setRespectBindingEnabled(respectBindingAnnotation.enabled());
- }
- }
-
- private void processHandlerChainAnnotation(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final HandlerChain handlerChainAnnotation = this.getAnnotation(serviceRefMD, HandlerChain.class);
-
- if (handlerChainAnnotation != null)
- {
- // Set the handlerChain from @HandlerChain on the annotated element
- String handlerChain = serviceRefMD.getHandlerChain();
- if (handlerChain == null && handlerChainAnnotation.file().length() > 0)
- handlerChain = handlerChainAnnotation.file();
-
- // Resolve path to handler chain
- if (handlerChain != null)
- {
- try
- {
- new URL(handlerChain);
- }
- catch (MalformedURLException ignored)
- {
- final AnnotatedElement annotatedElement = (AnnotatedElement) serviceRefMD.getAnnotatedElement();
- final Class<?> declaringClass = getDeclaringClass(annotatedElement);
-
- handlerChain = declaringClass.getPackage().getName().replace('.', '/') + "/" + handlerChain;
- }
-
- serviceRefMD.setHandlerChain(handlerChain);
- }
- }
- }
-
- private <T extends Annotation> T getAnnotation(final UnifiedServiceRefMetaData serviceRefMD, Class<T> annotationClass)
- {
- final AnnotatedElement annotatedElement = (AnnotatedElement) serviceRefMD.getAnnotatedElement();
-
- return annotatedElement != null ? (T) annotatedElement.getAnnotation(annotationClass) : null;
- }
-
- private void processWsdlOverride(final UnifiedServiceRefMetaData serviceRefMD, final ClassLoader loader)
- {
- // Set the wsdlLocation if there is no override already
- final WebServiceRef serviceRefAnnotation = this.getWebServiceRefAnnotation(serviceRefMD);
- if (serviceRefMD.getWsdlOverride() == null && serviceRefAnnotation != null
- && serviceRefAnnotation.wsdlLocation().length() > 0)
- serviceRefMD.setWsdlOverride(serviceRefAnnotation.wsdlLocation());
-
- // Extract service QName for target service
- if (null == serviceRefMD.getServiceQName())
- {
- try
- {
- Class<?> serviceClass = loader.loadClass(serviceRefMD.getServiceImplClass());
- if (serviceClass.getAnnotation(WebServiceClient.class) != null)
- {
- WebServiceClient clientDecl = (WebServiceClient) serviceClass.getAnnotation(WebServiceClient.class);
- serviceRefMD.setServiceQName(new QName(clientDecl.targetNamespace(), clientDecl.name()));
- //use the @WebServiceClien(wsdlLocation=...) if the service ref wsdl location returned at this time would be null
- if (clientDecl.wsdlLocation().length() > 0 && serviceRefMD.getWsdlLocation() == null)
- {
- serviceRefMD.setWsdlOverride(clientDecl.wsdlLocation());
- }
- }
- }
- catch (ClassNotFoundException e)
- {
- WSFException.rethrow("Cannot extract service QName for target service", e);
- }
- }
- }
-
- private Class<?> getDeclaringClass(final AnnotatedElement annotatedElement)
- {
- Class<?> declaringClass = null;
- if (annotatedElement instanceof Field)
- declaringClass = ((Field) annotatedElement).getDeclaringClass();
- else if (annotatedElement instanceof Method)
- declaringClass = ((Method) annotatedElement).getDeclaringClass();
- else if (annotatedElement instanceof Class)
- declaringClass = (Class<?>) annotatedElement;
-
- return declaringClass;
- }
-
- private Class<?> getTargetClass(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final AnnotatedElement annotatedElement = (AnnotatedElement) serviceRefMD.getAnnotatedElement();
-
- Class<?> targetClass = null;
-
- if (annotatedElement instanceof Field)
- {
- targetClass = ((Field) annotatedElement).getType();
- }
- else if (annotatedElement instanceof Method)
- {
- targetClass = ((Method) annotatedElement).getParameterTypes()[0];
- }
- else
- {
- final WebServiceRef serviceRefAnnotation = this.getWebServiceRefAnnotation(serviceRefMD);
- if (serviceRefAnnotation != null && (serviceRefAnnotation.type() != Object.class))
- targetClass = serviceRefAnnotation.type();
- }
-
- return targetClass;
- }
-
- private String getServiceImplClassName(final UnifiedServiceRefMetaData serviceRefMD)
- {
- String serviceImplClass = null;
-
- // #1 Use the explicit @WebServiceRef.value
- final WebServiceRef serviceRefAnnotation = this.getWebServiceRefAnnotation(serviceRefMD);
- if (serviceRefAnnotation != null && serviceRefAnnotation.value() != Service.class)
- serviceImplClass = serviceRefAnnotation.value().getName();
-
- // #2 Use the target ref type
- final Class<?> targetClass = getTargetClass(serviceRefMD);
- if (serviceImplClass == null && targetClass != null && Service.class.isAssignableFrom(targetClass))
- serviceImplClass = targetClass.getName();
-
- // #3 Use <service-interface>
- if (serviceImplClass == null && serviceRefMD.getServiceInterface() != null)
- serviceImplClass = serviceRefMD.getServiceInterface();
-
- // #4 Use javax.xml.ws.Service
- if (serviceImplClass == null)
- serviceImplClass = Service.class.getName();
-
- return serviceImplClass;
- }
-
- private WebServiceRef getWebServiceRefAnnotation(final UnifiedServiceRefMetaData serviceRefMD)
- {
- final WebServiceRef webServiceRefAnnotation = this.getAnnotation(serviceRefMD, WebServiceRef.class);
- final WebServiceRefs webServiceRefsAnnotation = this.getAnnotation(serviceRefMD, WebServiceRefs.class);
-
- if (webServiceRefAnnotation == null && webServiceRefsAnnotation == null)
- {
- return null;
- }
-
- // Build the list of @WebServiceRef relevant annotations
- final List<WebServiceRef> wsrefList = new ArrayList<WebServiceRef>();
-
- if (webServiceRefAnnotation != null)
- {
- wsrefList.add(webServiceRefAnnotation);
- }
-
- if (webServiceRefsAnnotation != null)
- {
- for (final WebServiceRef webServiceRefAnn : webServiceRefsAnnotation.value())
- {
- wsrefList.add(webServiceRefAnn);
- }
- }
-
- // Return effective @WebServiceRef annotation
- WebServiceRef returnValue = null;
- if (wsrefList.size() == 1)
- {
- returnValue = wsrefList.get(0);
- }
- else
- {
- for (WebServiceRef webServiceRefAnn : wsrefList)
- {
- if (serviceRefMD.getServiceRefName().endsWith(webServiceRefAnn.name()))
- {
- returnValue = webServiceRefAnn;
- break;
- }
- }
- }
-
- return returnValue;
- }
-}
14 years, 4 months
- 1
- 0
JBossWS SVN: r13205 - spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref.
by jbossws-commits＠lists.jboss.org
Author: richard.opalka(a)jboss.com
Date: 2010-11-03 04:05:39 -0400 (Wed, 03 Nov 2010)
New Revision: 13205
Modified:
spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java
Log:
[JBWS-3152] refactoring - cleanup service ref SPI
Modified: spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java 2010-11-03 07:55:37 UTC (rev 13204)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java 2010-11-03 08:05:39 UTC (rev 13205)
@@ -51,8 +51,9 @@
*
* @author Thomas.Diesler(a)jboss.org
* @author alessio.soldano(a)jboss.com
+ * @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
*/
-public class UnifiedServiceRefMetaData extends ServiceRefElement
+public final class UnifiedServiceRefMetaData extends ServiceRefElement
{
private static final long serialVersionUID = -926464174132493955L;
@@ -106,11 +107,6 @@
// @RespectBinding annotation metadata
private boolean respectBindingEnabled;
- // The JAXWS annotated element. JDK1.4 does not have java.lang.reflect.AnnotatedElement so we use an untyped Object
- private transient Object anElement;
- // A flag that should be set when this service-ref has been bound.
- private transient boolean processed;
-
public UnifiedServiceRefMetaData(UnifiedVirtualFile vfRoot)
{
this.vfsRoot = vfRoot;
@@ -408,27 +404,6 @@
this.handlerChain = handlerChain;
}
- public Object getAnnotatedElement()
- {
- return anElement;
-
- }
-
- public boolean isProcessed()
- {
- return processed;
- }
-
- public void setProcessed(boolean flag)
- {
- this.processed = flag;
- }
-
- public void setAnnotatedElement(Object anElement)
- {
- this.anElement = anElement;
- }
-
private void writeObject(ObjectOutputStream out) throws IOException
{
out.defaultWriteObject();
@@ -508,7 +483,6 @@
str.append("\n serviceImplClass=" + serviceImplClass);
str.append("\n serviceRefType=" + serviceRefType);
str.append("\n serviceQName=" + serviceQName);
- str.append("\n anElement=" + anElement);
str.append("\n wsdlFile=" + wsdlFile);
str.append("\n wsdlOverride=" + wsdlOverride);
str.append("\n mappingFile=" + mappingFile);
@@ -521,7 +495,6 @@
str.append("\n mtomEnabled=" + mtomEnabled);
str.append("\n mtomThreshold=" + mtomThreshold);
str.append("\n respectBindingEnabled=" + respectBindingEnabled);
- str.append("\n processed=" + processed);
str.append("\n handlerChains=" + handlerChains);
str.append("\n handlerChain=" + handlerChain);
for (UnifiedHandlerMetaData uhmd : handlers)
14 years, 4 months
- 1
- 0
JBossWS SVN: r13204 - in spi/trunk/src/main/java/org/jboss/wsf/spi: serviceref and 1 other directory.
by jbossws-commits＠lists.jboss.org
Author: richard.opalka(a)jboss.com
Date: 2010-11-03 03:55:37 -0400 (Wed, 03 Nov 2010)
New Revision: 13204
Removed:
spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefMetaData.java
Modified:
spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java
spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinder.java
spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinderFactory.java
spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefHandler.java
Log:
[JBWS-3152] refactoring - cleanup service ref SPI
Modified: spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java 2010-11-03 07:52:01 UTC (rev 13203)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/metadata/j2ee/serviceref/UnifiedServiceRefMetaData.java 2010-11-03 07:55:37 UTC (rev 13204)
@@ -42,7 +42,7 @@
import org.jboss.logging.Logger;
import org.jboss.wsf.spi.deployment.UnifiedVirtualFile;
import org.jboss.wsf.spi.deployment.WritableUnifiedVirtualFile;
-import org.jboss.wsf.spi.serviceref.ServiceRefMetaData;
+import org.jboss.wsf.spi.serviceref.ServiceRefElement;
import org.jboss.wsf.spi.util.URLLoaderAdapter;
/**
@@ -52,7 +52,7 @@
* @author Thomas.Diesler(a)jboss.org
* @author alessio.soldano(a)jboss.com
*/
-public class UnifiedServiceRefMetaData extends ServiceRefMetaData
+public class UnifiedServiceRefMetaData extends ServiceRefElement
{
private static final long serialVersionUID = -926464174132493955L;
Modified: spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinder.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinder.java 2010-11-03 07:52:01 UTC (rev 13203)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinder.java 2010-11-03 07:55:37 UTC (rev 13204)
@@ -21,10 +21,6 @@
*/
package org.jboss.wsf.spi.serviceref;
-import java.lang.reflect.AnnotatedElement;
-
-import javax.naming.Context;
-import javax.naming.NamingException;
import javax.naming.Referenceable;
import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
@@ -32,16 +28,9 @@
/**
* Creates a ServiceReferenceable and binds it to JNDI.
*
- * @author Heiko.Braun(a)jboss.com
* @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
*/
public interface ServiceRefBinder
{
- /**
- * @deprecated use {@link #createReferenceable(UnifiedServiceRefMetaData, ClassLoader)} instead
- */
- @Deprecated
- void setupServiceRef(Context encCtx, String encName, AnnotatedElement anElement, UnifiedServiceRefMetaData serviceRef, ClassLoader loader) throws NamingException;
- Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRef,
- final ClassLoader loader);
+ Referenceable createReferenceable(final UnifiedServiceRefMetaData serviceRef);
}
Modified: spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinderFactory.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinderFactory.java 2010-11-03 07:52:01 UTC (rev 13203)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefBinderFactory.java 2010-11-03 07:55:37 UTC (rev 13204)
@@ -25,7 +25,6 @@
/**
* @author Thomas.Diesler(a)jboss.com
- * @since 01-Aug-2007
*/
public interface ServiceRefBinderFactory extends SPIView
{
Modified: spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefHandler.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefHandler.java 2010-11-03 07:52:01 UTC (rev 13203)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefHandler.java 2010-11-03 07:55:37 UTC (rev 13204)
@@ -21,38 +21,21 @@
*/
package org.jboss.wsf.spi.serviceref;
-import javax.naming.Context;
-import javax.naming.NamingException;
import javax.naming.Referenceable;
-import org.jboss.wsf.spi.deployment.UnifiedVirtualFile;
import org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData;
/**
* An implementation of this interface handles all service-ref binding concerns.
- *
- * @author Thomas.Diesler(a)jboss.org
+ *
* @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
*/
public interface ServiceRefHandler
{
- enum Type {
+ enum Type
+ {
JAXRPC, JAXWS
};
- /**
- * @deprecated use {@link #createReferenceable(org.jboss.wsf.spi.metadata.j2ee.serviceref.UnifiedServiceRefMetaData, ClassLoader)} instead
- */
- @Deprecated
- void bindServiceRef(Context encCtx, String encName, UnifiedVirtualFile vfsRoot, ClassLoader loader,
- ServiceRefMetaData sref) throws NamingException;
-
- /**
- * Creates JNDI referenceable representing this <b>serviceRef</b>.
- *
- * @param serviceRefUMDM service reference UMDM
- * @param loader class loader
- * @return JNDI referenceable
- */
- Referenceable createReferenceable(UnifiedServiceRefMetaData serviceRefUMDM, ClassLoader loader);
+ Referenceable createReferenceable(UnifiedServiceRefMetaData serviceRefUMDM);
}
Deleted: spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefMetaData.java
===================================================================
--- spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefMetaData.java 2010-11-03 07:52:01 UTC (rev 13203)
+++ spi/trunk/src/main/java/org/jboss/wsf/spi/serviceref/ServiceRefMetaData.java 2010-11-03 07:55:37 UTC (rev 13204)
@@ -1,43 +0,0 @@
-/*
- * JBoss, Home of Professional Open Source.
- * Copyright 2006, Red Hat Middleware LLC, and individual contributors
- * as indicated by the @author tags. See the copyright.txt file in the
- * distribution for a full listing of individual contributors.
- *
- * This is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License as
- * published by the Free Software Foundation; either version 2.1 of
- * the License, or (at your option) any later version.
- *
- * This software is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License along with this software; if not, write to the Free
- * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
- * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
- */
-package org.jboss.wsf.spi.serviceref;
-
-/**
- * An abstract service-ref meta data object.
- *
- * @author Thomas.Diesler(a)jboss.org
- * @since 08-Mar-2007
- */
-public abstract class ServiceRefMetaData extends ServiceRefElement
-{
- public abstract String getServiceRefName();
-
- public abstract void setServiceRefName(String name);
-
- public abstract Object getAnnotatedElement();
-
- public abstract void setAnnotatedElement(Object anElement);
-
- public abstract boolean isProcessed();
-
- public abstract void setProcessed(boolean flag);
-}
14 years, 4 months
- 1
- 0
JBossWS SVN: r13203 - stack/native/trunk/src/main/doc.
by jbossws-commits＠lists.jboss.org
Author: alessio.soldano(a)jboss.com
Date: 2010-11-03 03:52:01 -0400 (Wed, 03 Nov 2010)
New Revision: 13203
Modified:
stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
Log:
[JBWS-2215] Fix to common user guide
Modified: stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml 2010-11-02 19:25:45 UTC (rev 13202)
+++ stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml 2010-11-03 07:52:01 UTC (rev 13203)
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-UserGuide"><title>JBossWS-UserGuide</title><para/><section id="JBossWS-UserGuide_Introduction_and_architecture"><title>Introduction and architecture</title><para> </para><para>The high level architecture of the JBossWS Web Service Framework is presented in the image here below:</para><para><ulink url="http://jboss.org/file-access/default/members/jbossws/images/wsf.png"><mediaobject><imageobject><imagedata fileref="images/wsf.png" depth="436" width="579"/></imageobject></mediaobject></ulink></para><para> </para><para>This basically means users can choose to download, install and use three different JBossWS versions:</para><itemizedlist><listitem><para><emphasis role="bold">JBossWS Native</emphasis>: this is the JBossWS Web Service Framework integrating the original JBossWS native stack that has been developed in the past years. This is what currently comes installed by default in every JBoss Application Server!
released version and has been used on top of JBoss AS 5 to make it successfully certified for Java EE 5. Please refer the <link linkend="chap_JBossWS-NativeUserGuide">JBossWS Native stack user guide</link> for a complete documentation of JBossWS-Native specific features.</para></listitem><listitem><para><emphasis role="bold">JBossWS CXF</emphasis>: this is the JBossWS Web Service Framework integrating the <ulink url="http://cxf.apache.org/">Apache CXF</ulink> web service stack. Please refer the <ulink url="http://community.jboss.org/docs/DOC-13562">JBossWS CXF stack user guide</ulink> for a complete documentation of JBossWS-CXF specific features.</para></listitem><listitem><para><emphasis role="bold">JBossWS Metro</emphasis>: this is the JBossWS Web Service Framework integrating the <ulink url="https://metro.dev.java.net/">GlassFish Metro</ulink> web service stack. Please refer the <ulink url="http://community.jboss.org/docs/DOC-13561">JBossWS Metro stack user guide</ulink!
> for a complete documentation of JBossWS-Metro specific featu!
res.</pa
ra></listitem></itemizedlist><para> </para><para>The JBossWS web service framework provides common features, tooling, management, deployment framework, etc. for all the supported stacks. At the same time, each stack comes with its own specific functional feature set, performance characteristics and -of course- community. So users can definitely choose the stack that best suits their needs and successfully use it on top of JBoss Application Server.</para><para> </para></section>
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-UserGuide"><title>JBossWS-UserGuide</title><para/>
<section id="JBossWS-UserGuide_Common_User_Guide"><title>Common User Guide</title><para> </para><para>Here below is the documentation that applies to every supported stacks. This includes basic JAX-WS usage as well as references to common additional functionalities the JBossWS Web Service Framework provides on top of the supported stacks.</para><section id="JBossWS-UserGuide_Web_Service_Concepts"><title>Web Service Concepts</title><section id="JBossWS-UserGuide_DocumentLiteral"><title>Document/Literal</title><para>With document style web services two business partners agree on the exchange of complex business documents that are well defined in XML schema. For example, one party sends a document describing a purchase order, the other responds (immediately or later) with a document that describes the status of the purchase order. No need to agree on such low level details as operation names and their associated parameters.</para><para>The payload of the SOAP message is an XM!
L document that can be validated against XML schema.</para><para>Document is defined by the style attribute on the SOAP binding.</para><screen xml:space="preserve"> <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
<soap:binding style='document' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
<operation name='concat'>
14 years, 4 months
- 1
- 0
JBossWS SVN: r13202 - in stack/native/trunk: src/main and 2 other directories.
by jbossws-commits＠lists.jboss.org
Author: alessio.soldano(a)jboss.com
Date: 2010-11-02 15:25:45 -0400 (Tue, 02 Nov 2010)
New Revision: 13202
Added:
stack/native/trunk/src/main/doc/
stack/native/trunk/src/main/doc/Author_Group.xml
stack/native/trunk/src/main/doc/Book_Info.xml
stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml
stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml
stack/native/trunk/src/main/doc/JBossWS-Authentication.xml
stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml
stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
stack/native/trunk/src/main/doc/JBossWS-Native.xml
stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml
stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml
stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml
stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml
stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml
stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml
stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml
stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml
stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml
stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml
Modified:
stack/native/trunk/pom.xml
stack/native/trunk/src/main/scripts/assembly-bin-dist.xml
Log:
[JBWS-2215] Adding docbook files and including doc generation in bin dist creation
Modified: stack/native/trunk/pom.xml
===================================================================
--- stack/native/trunk/pom.xml 2010-11-02 18:02:20 UTC (rev 13201)
+++ stack/native/trunk/pom.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -388,6 +388,32 @@
<!-- Plugins -->
<build>
+
+ <!-- PluginMangament-->
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.1.2</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.0.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
@@ -474,6 +500,49 @@
</descriptors>
</configuration>
</plugin>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>resources</goal>
+ <goal>generate</goal>
+ </goals>
+ <phase>package</phase>
+ </execution>
+ </executions>
+ <configuration>
+ <sourceDocumentName>JBossWS-Native.xml</sourceDocumentName>
+ <sourceDirectory>src/main/doc</sourceDirectory>
+ <imageResource>
+ <directory>src/main/doc</directory>
+ <includes>
+ <include>images/*</include>
+ </includes>
+ </imageResource>
+ <formats>
+ <!--format>
+ <formatName>pdf</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>JBossWS-Native_Guide.pdf</finalName>
+ </format-->
+ <format>
+ <formatName>html</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ </options>
+ </configuration>
+ </plugin>
</plugins>
</build>
</profile>
Added: stack/native/trunk/src/main/doc/Author_Group.xml
===================================================================
--- stack/native/trunk/src/main/doc/Author_Group.xml (rev 0)
+++ stack/native/trunk/src/main/doc/Author_Group.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ ]>
+<authorgroup>
+ <author>
+ <firstname>Alessio</firstname>
+ <surname>Soldano</surname>
+ </author>
+ <author>
+ <firstname>Richard</firstname>
+ <surname>Opalka</surname>
+ </author>
+ <author>
+ <firstname>Jim</firstname>
+ <surname>Ma</surname>
+ </author>
+</authorgroup>
Added: stack/native/trunk/src/main/doc/Book_Info.xml
===================================================================
--- stack/native/trunk/src/main/doc/Book_Info.xml (rev 0)
+++ stack/native/trunk/src/main/doc/Book_Info.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,14 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<bookinfo>
+<title>JBossWS-Native Guide</title>
+ <subtitle>JBoss Web Services with Native stack</subtitle>
+ <productname>JBossWS-Native</productname>
+ <!-- <pubdate>Nov 2010</pubdate> -->
+ <abstract>
+ <para>This book is the guide to JBoss Web Services with Native stack. It covers information, details and usage of JBossWS-Native stack, as well as some tutorials / examples.</para>
+ </abstract>
+ <!-- <subtitle>Authors</subtitle>-->
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
Added: stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Advancedsamples.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Advancedsamples"><title>JBossWS-Advancedsamples</title><para>The aim of this page is to help users coping with real world usecases. For this reason some advanced sample have been developed.</para><para> </para><section><title>How to use the advanced samples</title><para>The JBossWS <ulink url="http://community.jboss.org/docs/DOC-13550">basic samples</ulink> introduce you to most of the available features, showing you how to use each of them through simple JUnit test cases.</para><para> </para><para>Instead the advanced samples covered here have their own scenario linking them to a real world use case. They are meant to be used as stand alone applications: different reliable implementations are proposed for each scenario, leveraging the most suitable JBossWS features. The choices taken for the key points of each usecase are then discussed. You should follow the steps in the documentation and run the applicatio!
ns whenever you're invited to. This way you'll be able to understand the advantages and disadvantages of each solution.</para><para> </para><para>Right now the advanced sample are available in the source distribution only. You need to download it and run <emphasis>ant</emphasis> (default target) to compile everything. The advanced samples' archives (both client and server) are in the <emphasis>output/tests/lib</emphasis> directory like the other samples.</para><para> </para></section>
+<section><title>Available samples</title><itemizedlist><listitem><para> <link linkend="chap_JBossWS-Asynchronousinvocationssample">JBossWS - Asynchronous invocations sample</link>: <emphasis>Asynchronous invocations to long running ws endpoint operations</emphasis> </para></listitem><listitem><para> <link linkend="chap_JBossWS-Securityandattachmentssample">JBossWS - Security and attachments sample</link>: <emphasis>Security and attachments</emphasis> </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Articlesandspecs.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Articlesandspecs"><title>JBossWS-Articlesandspecs</title><section><title>J2EE-5.0 Web Services Specifications</title><itemizedlist><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=244">J2EE-5.0 - Java2 Enterprise Edition Specification (JSR244)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web Services (JSR921)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=220">EJB-3.0 - Enterprise Java Beans (JSR220)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=224">JAXWS-2.0 - Java API for XML-Based Web Services (JSR224)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=222">JAXB-2.0 - Java Architecture for XML Binding (JSR222)</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-!
part1">SOAP-1.2 - SOAP Messaging Framework</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-part0">SOAP-1.2 Primer</ulink> </para></listitem><listitem><para> <ulink url="http://schemas.xmlsoap.org/wsdl/soap12">WSDL 1.1 Binding Extension for SOAP 1.2</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20">WSDL-2.0 - Part 1: Core Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20-extensions">WSDL-2.0 - Part 2: Predefined Extensions</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20-bindings">WSDL-2.0 - Part 3: Bindings</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/2002/ws/desc/wsdl20-primer">WSDL-2.0 Primer</ulink> </para></listitem><listitem><para> <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">BP-1.1 - Basic Profile</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/de!
tail?id=181">JSR181 - Web Services Metadata</ulink> </para></l!
istitem>
<listitem><para> <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0.html">WS-I Attachments Profile 1.0</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink></para></listitem></itemizedlist></section>
+<section><title>J2EE-1.4 Web Services Specifications</title><itemizedlist><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/index.jsp">J2EE-1.4 - Java 2 Platform, Enterprise Edition (J2EE) 1.4</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web Services</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=153">EJB-2.1 - Enterprise Java Beans</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=101">JAXRPC-1.1 - Java API for XML-based RPC</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=67">SAAJ-1.2 - SOAP with Attachments</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=93">JAXR-1.0 - Java API for XML Registries</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1 - Simple Object Acc!
ess Protocol</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl">WSDL-1.1 - Web Services Description Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/REC-xml/">XML-1.0 - Extensible Markup Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-1/">XMLSchema - Structures</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-2/">XMLSchema - Data Types</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-0">XMLSchema Primer</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/REC-xml-names">XMLNS - Namespaces in XML</ulink> </para></listitem><listitem><para> <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0.html">BP-1.0 - Basic Profile</ulink></para></listitem></itemizedlist></section>
+<section><title>Optional advanced Web Services specifications</title><itemizedlist><listitem><para> <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobsp...">MSDN Web Services Specifications Index Page</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-330">WS-Distributed Managment</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-326">WS-Notification</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-76">WS-ReliableMessaging</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-329">WS-Resource</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-36">WS-Transaction</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.org/jira/browse/JBWS-447">WS-BPEL</ulink></para></listitem></itemizedlist><vari!
ablelist/><para>Please provide feedback on your needs of these optional WS specifications as this will influence what we will put on the <ulink url="http://jira.jboss.org/jira/browse/JBWS?report=com.atlassian.jira.plugin.s...">JBossWS roadmap</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Asynchronousinvocationssample.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,844 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Asynchronousinvocationssample"><title>JBossWS-Asynchronousinvocationssample</title><section id="JBossWS-Asynchronousinvocationssample_Scenario"><title>Scenario</title><para>This sample targets those business scenarios in which web services expose functionalities requiring long running processes. Service consumers send the message requests and don't want to actively wait for the response or use polling mechanism to find out whether their response is ready.</para><para> </para><para>The <emphasis role="bold">org.jboss.test.ws.jaxws.samples.dar</emphasis> sample is about a Dial-a-ride optimization service. The Dial-a-Ride (DaR) is an emerging transport system, in which a fleet of vehicles, without fixed routes and schedules, carries people from the desired pickup point to the desired delivery point, during a pre-specified time interval. Passengers ring the service provider office the day before they want to trave!
l and book their ride. An optimization system works out the route to be as efficient as possible, so that for instance people with similar travel requests are collected by the same vehicle. Since the problem can be modeled as an NP-hard routing and scheduling problem and exact approaches are insufficient for real-life problems, our software company decides to provide a service that solves the DaR problem for transportation companies' requests through complex custom heuristic algorithms. And of course, this takes some time.</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_The_service_provider"><title>The service provider</title><para>We start defining and implementing the DaR service provider (bottom-up approach):</para><screen xml:space="preserve">@Stateless
+@WebService(name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/dar",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="NONE",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarEndpoint
+{
+ @WebMethod(operationName = "process", action = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ <emphasis role="bold">public</emphasis> DarResponse process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis> DarProcessor();
+ <emphasis role="bold">return</emphasis> processor.process(request);
+ }
+}
+</screen><para>To keep this simple we use a SLSB endpoint and the rpc/literal style/use, of course you can choose POJO endpoint and the better document style as well. A BASIC authorization method is used to achieve request accountability; for ease we use the default JBossWS security domain, of course you would need to authenticate transport companies through your own login module as well as keep track of the requests for billing reasons. The DarProcessor performs the actual DaR problem solution and optimization. DarRequest and DarResponse, along with the referenced classes, define the request and response model, with the pickup and delivery point on the map, the departure/arrival times, etc. Every further detail (for instance about quality of service) is not considered to keep the sample simple.</para><para>You can build the sample, take a look at the simple service endpoint in <emphasis>jaxws-samples-dar.jar</emphasis> and deploy it.</para><screen xml:space="preserve">[ale!
ssio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 1643 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarEndpoint.class
+ 4231 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+</screen><para>Assume your bind address is <emphasis>localhost.localdomain:8080</emphasis>; the JBossWS stack will deploy the service and publish the wsdl contract at <ulink url="http://localhost.localdomain:8080/dar?wsdl">http://localhost.localdomain:8080/dar?wsdl</ulink>.</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_JAXWS_Asynchronous_API"><title>JAX-WS Asynchronous API</title><section id="JBossWS-Asynchronousinvocationssample_The_transportation_company_client"><title>The transportation company client</title><para>Once the first implementation of the service provider is ready, we generate a simple client to test it. This can be easily achieved with the <ulink url="http://community.jboss.org/docs/DOC-13542">wsconsume</ulink> script:</para><screen xml:space="preserve">wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.dar.generated http://localhost.localdomain:8080/dar?wsdl</screen><para>This outputs the endpoint interface that our client has to use, as well as all the classes for requests/responses. Since we need to perform asynchronous invocations using the <ulink url="http://community.jboss.org/docs/DOC-13972#Asynchronous_Invocations">JAX-WS async API</ulink>, we a need method with the same name of the existing one followed by <emphas!
is>Async</emphasis> and returning a javax.xml.ws.Response:</para><screen xml:space="preserve">@WebService(name = "DarEndpoint", targetNamespace = "http://org.jboss.ws/samples/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> DarEndpoint {
+
+ @WebMethod(operationName = "process")
+ <emphasis role="bold">public</emphasis> Response<DarResponse> processAsync(@WebParam(name = "arg0", partName = "arg0") DarRequest arg0);
+
+ @WebMethod(action = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ @WebResult(partName = "return")
+ <emphasis role="bold">public</emphasis> DarResponse process(@WebParam(name = "arg0", partName = "arg0") DarRequest arg0);
+}
+</screen><para>Then we implement the client, invoking both the method to see the different behaviors:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> Client
+{
+ <emphasis role="bold">protected</emphasis> DarEndpoint endpoint;
+
+ <emphasis role="bold">public</emphasis> Client(URL url)
+ {
+ DarService service = <emphasis role="bold">new</emphasis> DarService(url, <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/dar", "DarService"));
+ endpoint = service.getDarEndpointPort();
+ ClientHelper.setUsernamePassword((BindingProvider)endpoint, "kermit", "thefrog");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> run(<emphasis role="bold">boolean</emphasis> asynch) <emphasis role="bold">throws</emphasis> Exception
+ {
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Sending request...");
+ DarResponse darResponse;
+ <emphasis role="bold">if</emphasis> (asynch)
+ {
+ Response<DarResponse> response = endpoint.processAsync(request);
+ System.out.println("Doing something interesting in the mean time... ;-) ");
+ darResponse = response.get();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ darResponse = endpoint.process(request);
+ }
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Response received: "+darResponse);
+ ClientHelper.printResponse(darResponse);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ Client client = <emphasis role="bold">new</emphasis> Client(<emphasis role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Client usage:");
+ System.out.println("wsrunclient.sh -classpath client.jar org.jboss.test.ws.jaxws.samples.dar.Client http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>The ClientHelper contains utility methods for generating sample requests and outputting responses to the log. Here is how the client package looks like:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-client.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 3493 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Client.class
+ 4407 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class</screen></section>
+<section id="JBossWS-Asynchronousinvocationssample_Running_the_client"><title>Running the client</title><para>Now you can run the client and see whether we got the expected behavior:</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-dar-client.jar org.jboss.test.ws.jaxws.samples.dar.Client http://localhost.localdomain:8080/dar?wsdl
+</screen><para>As you can see from the output below, both the standard and asynchronous invocation took some time (5 sec):</para><screen xml:space="preserve">Synchronous invocation:
+Mon Feb 04 15:10:44 CET 2008 Sending request...
+Mon Feb 04 15:10:50 CET 2008 Response received: org.jboss.test.ws.jaxws.samples.dar.generated.DarResponse@1389b3f
+Bus1: 778 118 734 341
+Bus0: 298 142 788 876
+
+Asynchronous invocation:
+Mon Feb 04 15:10:50 CET 2008 Sending request...
+Doing something interesting in the mean time... ;-)
+Mon Feb 04 15:10:55 CET 2008 Response received: org.jboss.test.ws.jaxws.samples.dar.generated.DarResponse@1265109
+Bus1: 169 863
+Bus0: 951 28 244 903 226 159
+</screen><para>The use of the async invocation does not block the client and allows it to perform something else before waiting for the result from the server. We could have also used an AsyncHandler as showed in the <ulink url="http://community.jboss.org/docs/DOC-13550#orgjbosstestwsjaxwssamplesasync...">asynchronous simple test case</ulink>.</para><para> </para></section>
+</section>
+<section id="JBossWS-Asynchronousinvocationssample_WSAddressing"><title>WS-Addressing</title><para>Even if the client can do something else while the server handles the request, it would be better if the response could be received by another instance, leaving the client completely free go on with its business. <link linkend="WSAddressing">WS-Addressing</link> provides means of specifying which address the response has to be sent to. This is performed through the <emphasis>replyTo</emphasis> property.</para><section id="JBossWS-Asynchronousinvocationssample_Addressing_service_provider"><title>Addressing service provider</title><para>For this reason we create a new AddressingEndpoint:</para><screen xml:space="preserve">@Stateless
+@WebService(name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/dar",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="NONE",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+@EndpointConfig(configName = "Standard WSAddressing Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarAddressingEndpoint
+{
+ @Resource
+ <emphasis role="bold">private</emphasis> WebServiceContext ctx;
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> Logger log = Logger.getLogger(DarAddressingEndpoint.class);
+
+ @WebMethod(operationName = "process", action = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ @Action(input = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn", output = "http://org.jboss.test.ws.jaxws.samples.dar/action/processOut")
+ <emphasis role="bold">public</emphasis> DarResponse process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis> DarProcessor();
+ AddressingProperties props = (AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ <emphasis role="bold">if</emphasis> (props!=<emphasis role="bold">null</emphasis> && props.getReplyTo()!=<emphasis role="bold">null</emphasis>)
+ {
+ System.out.println(props.getReplyTo().getAddress().getURI());
+ }
+ <emphasis role="bold">return</emphasis> processor.process(request);
+ }
+}
+</screen><para>As you can see, we used the proper endpoint config and specified the input and output action names. The WS-Addressing implementation write/read the <emphasis>replyTo</emphasis> property to/from the SOAP header, thus the <emphasis>WebServiceContext</emphasis> allows us to retrieve the <emphasis>replyTo</emphasis> address to be used for the current invocation.</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_Addressing_client"><title>Addressing client</title><para>In order to provide the right <emphasis>replyTo</emphasis> address, the client side too needs to be changed:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> AddressingClient
+{
+ <emphasis role="bold">protected</emphasis> DarEndpoint endpoint;
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> AddressingBuilder BUILDER;
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String WSA_TO = "http://org.jboss.test.ws.jaxws.samples.dar/server";
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String WSA_ACTION = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn";
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String WSA_ACTION_ONEWAY = "http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn";
+
+ <emphasis role="bold">static</emphasis>
+ {
+ BUILDER = AddressingBuilder.getAddressingBuilder();
+ }
+
+ <emphasis role="bold">public</emphasis> AddressingClient(URL url)
+ {
+ DarService service = <emphasis role="bold">new</emphasis> DarService(url, <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/dar", "DarService"));
+ endpoint = service.getDarEndpointPort();
+ ((StubExt)endpoint).setConfigName("Standard WSAddressing Client");
+ ClientHelper.setUsernamePassword((BindingProvider)endpoint, "kermit", "thefrog");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> run(<emphasis role="bold">boolean</emphasis> asynch) <emphasis role="bold">throws</emphasis> Exception
+ {
+ configureAddressingProperties((BindingProvider)endpoint, WSA_ACTION, WSA_TO, "http://localhost:8080/dar-client/replyTo");
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Sending request...");
+ <emphasis role="bold">if</emphasis> (asynch)
+ {
+ Response<DarResponse> resp = endpoint.processAsync(request);
+ System.out.println("Doing something interesting in the mean time... ;-) ");
+ resp.get();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ endpoint.process(request);
+ }
+ //don't care about the response: it is null since the real one went to the replyTo address
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Done.");
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> configureAddressingProperties(BindingProvider bp, String wsaAction, String wsaTo, String replyTo) <emphasis role="bold">throws</emphasis> URISyntaxException
+ {
+ AddressingProperties requestProps = AddressingClientUtil.createDefaultProps(wsaAction, wsaTo);
+ AttributedURI messageId = AddressingClientUtil.createMessageID();
+ System.out.println("Sent message ID: " + messageId.getURI());
+ requestProps.setMessageID(messageId);
+ requestProps.setReplyTo(BUILDER.newEndpointReference(<emphasis role="bold">new</emphasis> URI(replyTo)));
+ bp.getRequestContext().put(JAXWSAConstants.CLIENT_ADDRESSING_PROPERTIES_OUTBOUND, requestProps);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ AddressingClient client = <emphasis role="bold">new</emphasis> AddressingClient(<emphasis role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("AddressingClient usage:");
+ System.out.println("wsrunclient.sh -classpath AddressingClient.jar org.jboss.test.ws.jaxws.samples.dar.AddressingClient http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>You can see in the <emphasis>configureAddressingProperties(...)</emphasis> method how the WS-Addressing properties are configured. The <emphasis>Standard WSAddressing Client</emphasis> client config needs also to be specified so that the WS-Addressing stack extension is used.</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_The_reply_sink"><title>The reply sink</title><para>Thanks to the WS-Addressing implementation, the server will automatically send the response to the specified address. Of course we need something to receive it; for ease here we have a simple servlet dumping everything to the logs:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ReplyToServlet <emphasis role="bold">extends</emphasis> HttpServlet {
+
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> doGet(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) <emphasis role="bold">throws</emphasis> ServletException, IOException {
+ dump(httpServletRequest, httpServletResponse);
+ }
+
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> doPost(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) <emphasis role="bold">throws</emphasis> ServletException, IOException {
+ dump(httpServletRequest, httpServletResponse);
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">void</emphasis> dump(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) {
+ System.out.println("ReplyTo sink:");
+
+ <emphasis role="bold">try</emphasis> {
+ BufferedReader reader = httpServletRequest.getReader();
+ String inputLine;
+
+ <emphasis role="bold">while</emphasis> ((inputLine = reader.readLine()) != <emphasis role="bold">null</emphasis>) {
+ System.out.println(inputLine);
+ }
+ reader.close();
+ } <emphasis role="bold">catch</emphasis> (IOException e) {
+ e.printStackTrace();
+ }
+
+ httpServletResponse.setStatus(200);
+ }
+}
+</screen><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_Oneway_invocations"><title>Oneway invocations</title><para>Having splitted the client is actually not enough. The reason is that even if the response is not received by the <emphasis>AddressingClient</emphasis>, with the current JBossWS stack implementation, the underlying connection between the ws consumer and provider is nevertheless closed once the latter has sent the response to the <emphasis>ReplyToServlet</emphasis> and this is a resource waste. Moreover, on the server side, since a new thread is spanned for each invocation, the long running process could cause the system to reach the max number of thread/http connections allowed at the same time.</para><para>For this reason, we split the service too. A oneway invocation is performed, then on the server side the collected requests are stored into a queue. A message driven bean consumes the queue, performs the long running optimization and finally replies to the addres!
s the client specified. The following paragraphs go deeper into the details.</para><para> </para><section id="JBossWS-Asynchronousinvocationssample_Response_service_implementation"><title>Response service implementation</title><para>To get what has just been summarized, the server has to send messages whose schema has to be somewhere declared: we'll use a top-down development strategy. Here is the hand-coded reply service wsdl contract:</para><screen xml:space="preserve"><definitions name="DarReplyService" targetNamespace="<ulink url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>" xmlns="<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>" xmlns:soap="<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>" xmlns:tns="<ulink url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>" xmlns:xsd="<ulink url="http://www.w3.org/2001/XMLSchema">http://www!
.w3.org/2001/XMLSchema</ulink>"><types>
+ <xs:schema targetNamespace="<ulink url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>" version="1.0" xmlns:tns="<ulink url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>" xmlns:xs="<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>">
+ <xs:complexType name="serviceRequest">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="from" type="tns:stop"/>
+ <xs:element minOccurs="0" name="id" type="xs:string"/>
+ <xs:element name="people" type="xs:int"/>
+ <xs:element minOccurs="0" name="to" type="tns:stop"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="stop">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="node" type="xs:int"/>
+ <xs:element minOccurs="0" name="time" type="xs:dateTime"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="darResponse">
+ <xs:sequence>
+ <xs:element maxOccurs="unbounded" minOccurs="0" name="routes" nillable="true" type="tns:route"/>
+ <xs:element maxOccurs="unbounded" minOccurs="0" name="unservedRequests" nillable="true" type="tns:serviceRequest"/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name="route">
+ <xs:sequence>
+ <xs:element minOccurs="0" name="busId" type="xs:string"/>
+ <xs:element maxOccurs="unbounded" minOccurs="0" name="stops" nillable="true" type="tns:stop"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema></types><message name="DarReplyEndpoint_receive">
+ <part name="arg0" type="tns:darResponse"/></message><portType name="DarReplyEndpoint">
+ <operation name="receive">
+ <input message="tns:DarReplyEndpoint_receive"/>
+ </operation></portType><binding name="DarReplyEndpointBinding" type="tns:DarReplyEndpoint">
+ <soap:binding style="rpc" transport="<ulink url="http://schemas.xmlsoap.org/soap/http">http://schemas.xmlsoap.org/soap/http</ulink>"/>
+ <operation name="receive">
+ <soap:operation soapAction="<ulink url="http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn">http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn</ulink>"/>
+ <input>
+ <soap:body namespace="<ulink url="http://org.jboss.ws/samples/dar">http://org.jboss.ws/samples/dar</ulink>" use="literal"/>
+ </input>
+ </operation></binding><service name="DarReplyService">
+ <port binding="tns:DarReplyEndpointBinding" name="DarReplyEndpointPort">
+ <soap:address location="<ulink url="http://localhost.localdomain:8080/dar-client/replyService">http://localhost.localdomain:8080/dar-client/replyService</ulink>"/>
+ </port></service>
+</definitions>
+</screen><para>The optimization system acts as a client here: it owns the schema and gets the interface through the wsconsume script:</para><screen xml:space="preserve">wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.dar.generated.reply reply.wsdl
+</screen><para>The transportation companies play the server role instead, thus they implement the generated endpoint interface:</para><screen xml:space="preserve">@WebService(name = "DarReplyEndpoint", targetNamespace = "http://org.jboss.ws/samples/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> DarReplyEndpoint {
+
+
+ /**
+ *
+ * @param arg0
+ */
+ @WebMethod(action = "http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> receive(
+ @WebParam(name = "arg0", partName = "arg0")
+ DarResponse arg0);
+
+}
+</screen><para>Here is the endpoint implementation: as for the request service, the addressing configuration is specified as well as the action for the oneway operation.</para><screen xml:space="preserve">@WebService(name = "DarReplyEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.dar.generated.reply.DarReplyEndpoint",
+ wsdlLocation = "/WEB-INF/wsdl/reply.wsdl",
+ serviceName = "DarReplyService")
+@SOAPBinding(style = Style.RPC,
+ use = Use.LITERAL)
+@EndpointConfig(configName = "Standard WSAddressing Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarReplyEndpointImpl <emphasis role="bold">implements</emphasis> DarReplyEndpoint
+{
+ @Resource
+ <emphasis role="bold">private</emphasis> WebServiceContext ctx;
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> Logger log = Logger.getLogger(DarReplyEndpointImpl.class);
+
+ @WebMethod(action = "http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ @Oneway
+ @Action(input = "http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn")
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> receive(DarResponse arg0)
+ {
+ AddressingProperties props = (AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ log.info("Result received; relationship message id: " + props.getRelatesTo()[0].getID());
+ List<Route> routes = arg0.getRoutes();
+ <emphasis role="bold">for</emphasis> (Route route : routes)
+ {
+ log.info(route.getBusId() + ": ");
+ StringBuilder sb = <emphasis role="bold">new</emphasis> StringBuilder();
+ <emphasis role="bold">for</emphasis> (Stop stop : route.getStops())
+ {
+ sb.append(stop.getNode() + " ");
+ }
+ log.info(sb.toString());
+ }
+ }
+}
+</screen></section>
+<section id="JBossWS-Asynchronousinvocationssample_Request_service_improvements"><title>Request service improvements</title><para>Finally the request service endpoint needs a new oneway operation method:</para><screen xml:space="preserve"> @WebMethod(operationName = "onewayProcess", action = "http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn")
+ @Action(input = "http://org.jboss.test.ws.jaxws.samples.dar/action/onewayProcessIn")
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> onewayProcess(DarRequest request)
+ {
+ QueueSession queueSession =<emphasis role="bold">null</emphasis>;
+ QueueSender sender = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis> {
+ InitialContext context = <emphasis role="bold">new</emphasis> InitialContext();
+ QueueConnectionFactory connectionFactory = (QueueConnectionFactory)context.lookup("ConnectionFactory");
+ QueueConnection con = connectionFactory.createQueueConnection();
+ queueSession = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+ Queue queue = (Queue)context.lookup("queue/DarQueue");
+ sender = queueSession.createSender(queue);
+ AsyncProcessRequest asyncRequest = <emphasis role="bold">new</emphasis> AsyncProcessRequest();
+ asyncRequest.setRequest(request);
+ AddressingProperties props = (AddressingProperties)ctx.getMessageContext().get(JAXWSAConstants.SERVER_ADDRESSING_PROPERTIES_INBOUND);
+ asyncRequest.setReplyTo(props.getReplyTo().getAddress().getURI());
+ asyncRequest.setMessageId(props.getMessageID().getURI());
+ ObjectMessage message = queueSession.createObjectMessage(asyncRequest);
+ sender.send(message);
+ log.info("AsyncProcessRequest sent...");
+ } <emphasis role="bold">catch</emphasis> (Exception e) {
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> WebServiceException(e);
+ } <emphasis role="bold">finally</emphasis> {
+ <emphasis role="bold">try</emphasis>
+ {
+ sender.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ <emphasis role="bold">try</emphasis>
+ {
+ queueSession.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ }
+
+ }
+</screen><para>As you can see this does a lookup of the local <emphasis>queue/DarQueue</emphasis> and sends a custom <emphasis>AsyncProcessRequest</emphasis> pojo. This way the invocation is served and the endpoint thread is ready to receive another request.</para><para>The afore-mentioned queue is consumed by the following Message Driven bean:</para><screen xml:space="preserve">@MessageDriven( name="DarListener", activationConfig= {
+ @ActivationConfigProperty(propertyName="destinationType",propertyValue="javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName="destination",propertyValue="queue/DarQueue")}
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarMessageBean <emphasis role="bold">implements</emphasis> MessageListener
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> Logger log = Logger.getLogger(DarMessageBean.class);
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String WSA_ACTION = "http://org.jboss.test.ws.jaxws.samples.dar/action/receiveIn";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> onMessage(Message arg0)
+ {
+ <emphasis role="bold">try</emphasis> {
+ ObjectMessage message = (ObjectMessage)arg0;
+ AsyncProcessRequest asyncRequest = (AsyncProcessRequest)message.getObject();
+ DarProcessor processor = <emphasis role="bold">new</emphasis> DarProcessor();
+ DarResponse response = processor.process(asyncRequest.getRequest());
+
+ //convert the response and send it to the client reply service
+ org.jboss.test.ws.jaxws.samples.dar.generated.reply.DarResponse darResponse = ReplyConverter.convertResponse(response);
+ String replyTo = asyncRequest.getReplyTo().toURL().toString();
+ log.info("Response will be sent to: " + replyTo);
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/dar", "DarReplyService");
+ Service service = Service.create(<emphasis role="bold">new</emphasis> URL(replyTo + "?wsdl"), serviceName);
+ DarReplyEndpoint endpoint = (DarReplyEndpoint)service.getPort(DarReplyEndpoint.class);
+
+ //setup addressing configuration and properties
+ ((StubExt)endpoint).setConfigName("Standard WSAddressing Client");
+ ((BindingProvider)endpoint).getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, replyTo);
+ AddressingProperties requestProps = AddressingClientUtil.createOneWayProps(WSA_ACTION, replyTo);
+ requestProps.setMessageID(AddressingClientUtil.createMessageID());
+ Relationship[] relationships = <emphasis role="bold">new</emphasis> Relationship[1];
+ relationships[0] = <emphasis role="bold">new</emphasis> RelationshipImpl(asyncRequest.getMessageId());
+ requestProps.setRelatesTo(relationships);
+ ((BindingProvider)endpoint).getRequestContext().put(JAXWSAConstants.CLIENT_ADDRESSING_PROPERTIES_OUTBOUND, requestProps);
+
+ endpoint.receive(darResponse);
+ log.info("Response sent.");
+ } <emphasis role="bold">catch</emphasis> (Exception e) {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>This basically delegates to the DarProcessor then invokes the transportation company endpoint. Please note that:</para><itemizedlist><listitem><para> the <emphasis>Standard WSAddressing Client</emphasis> configuration is used so that reply message ID can be associated to the request message ID; this allows the transportation company to to link requests and responses; </para></listitem><listitem><para> the endpoint address is of course set at runtime according to the <emphasis>replyTo</emphasis> addressing property found in the request message; </para></listitem><listitem><para> a stupid <emphasis>ReplyConverter</emphasis> is used since the classes generated from the hand-coded wsdl contract differ from the server model ones.</para></listitem></itemizedlist><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_Addressing_client_changes"><title>Addressing client changes</title><para>On the transportation company side, we have a new <emphasis>AddressingClient</emphasis>'s method for the oneway request service invocation:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> runOneway() <emphasis role="bold">throws</emphasis> Exception
+ {
+ configureAddressingProperties((BindingProvider)endpoint, WSA_ACTION_ONEWAY, WSA_TO, "http://localhost:8080/dar-client/replyService");
+ DarRequest request = ClientHelper.getRequest();
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Sending request...");
+ endpoint.onewayProcess(request);
+ System.out.println(<emphasis role="bold">new</emphasis> Date() + " Done.");
+ }
+</screen><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ AddressingClient client = <emphasis role="bold">new</emphasis> AddressingClient(<emphasis role="bold">new</emphasis> URL(args[0]));
+ System.out.println("* Synchronous invocation: ");
+ client.run(<emphasis role="bold">false</emphasis>);
+ System.out.println("\n* Asynchronous invocation: ");
+ client.run(<emphasis role="bold">true</emphasis>);
+ System.out.println("\n* Oneway invocation: ");
+ client.runOneway();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("AddressingClient usage:");
+ System.out.println("wsrunclient.sh -classpath AddressingClient.jar org.jboss.test.ws.jaxws.samples.dar.AddressingClient http://host:port/dar?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+</screen></section>
+<section id="JBossWS-Asynchronousinvocationssample_Running_the_sample"><title>Running the sample</title><para>Before trying the new addressing version of this sample, please take a look at the three archives you'll use. The <emphasis>jaxws-samples-dar-addressing.jar</emphasis> contains the optimization system:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-addressing.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 1175 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/AsyncProcessRequest.class
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 5258 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarAddressingEndpoint.class
+ 4751 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarMessageBean.class
+ 4231 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 3747 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ReplyConverter.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/
+ 847 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyEndpoint.class
+ 1680 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyService.class
+ 1425 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarResponse.class
+ 1336 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/ObjectFactory.class
+ 1291 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/Route.class
+ 1619 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/ServiceRequest.class
+ 1222 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/Stop.class
+ 288 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/reply/package-info.class
+</screen><para>The <emphasis>jaxws-samples-dat-addressing-client.jar</emphasis> is the first (request) part of the transportation companies software:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-addressing-client.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 5859 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/AddressingClient.class
+ 4407 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class
+</screen><para>Finally, the <emphasis>jaxws-samples-dar-addressing-client.war</emphasis> is the second (response) part of the transportation company, including both the sink servlet and the DarReplyEndpointImpl for response receipt:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-addressing-client.war
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 01 17:55:20 CET 2008 WEB-INF/
+ 941 Thu Jan 31 16:07:30 CET 2008 WEB-INF/web.xml
+ 0 Fri Feb 01 17:55:20 CET 2008 WEB-INF/classes/
+ 0 Thu Jan 10 21:41:02 CET 2008 WEB-INF/classes/org/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/
+ 3850 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/DarReplyEndpointImpl.class
+ 1612 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/ReplyToServlet.class
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/
+ 847 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyEndpoint.class
+ 1680 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarReplyService.class
+ 1425 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/DarResponse.class
+ 1336 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/ObjectFactory.class
+ 1291 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/Route.class
+ 1619 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/ServiceRequest.class
+ 1222 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/Stop.class
+ 288 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/reply/package-info.class
+ 228 Wed Jan 30 00:44:14 CET 2008 WEB-INF/jboss-web.xml
+ 0 Thu Jan 31 16:07:30 CET 2008 WEB-INF/wsdl/
+ 2457 Thu Jan 31 16:07:30 CET 2008 WEB-INF/wsdl/reply.wsdl
+</screen><para>You have to deploy both the <emphasis>jaxws-samples-dar-addressing.jar</emphasis> and the <emphasis>jaxws-samples-dar-addressing-client.war</emphasis>; for ease we run the transportation company receipt system on the same host of the optimization system, of course you can play with the addresses and simulate a real world architecture using two hosts. Then we run the request service client...</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-dar-addressing-client.jar org.jboss.test.ws.jaxws.samples.dar.AddressingClient http://localhost.localdomain:8080/dar?wsdl
+</screen><para>...and verify the obtained behavior checking the log on the client side:</para><screen xml:space="preserve">* Synchronous invocation:
+Sent message ID: urn:uuid:321dee7b-953c-4405-9b06-dbc6743d36e6
+Tue Feb 05 11:31:37 CET 2008 Sending request...
+[Fatal Error] :-1:-1: Premature end of file.
+Tue Feb 05 11:31:42 CET 2008 Done.
+
+* Asynchronous invocation:
+Sent message ID: urn:uuid:b9076402-f52-4aca-9e5b-b6e80cf1c3e2
+Tue Feb 05 11:31:42 CET 2008 Sending request...
+Doing something interesting in the mean time... ;-)
+[Fatal Error] :-1:-1: Premature end of file.
+Tue Feb 05 11:31:47 CET 2008 Done.
+
+* Oneway invocation:
+Sent message ID: urn:uuid:cc5d90d1-d95-450d-a0cc-3a025f49d6c3
+Tue Feb 05 11:31:47 CET 2008 Sending request...
+Tue Feb 05 11:31:47 CET 2008 Done.
+</screen><para>... and on the server side:</para><screen xml:space="preserve">11:31:37,218 INFO [STDOUT] http://localhost:8080/dar-client/replyTo
+11:31:37,218 INFO [DarProcessor] Processing DAR request... org.jboss.test.ws.jaxws.samples.dar.DarRequest@1c2cbee
+11:31:37,218 INFO [DarProcessor] 1 person(s) from 582 to 662
+11:31:37,218 INFO [DarProcessor] 2 person(s) from 260 to 962
+11:31:37,218 INFO [DarProcessor] 1 person(s) from 10 to 959
+11:31:37,218 INFO [DarProcessor] 3 person(s) from 138 to 722
+11:31:42,219 INFO [DarProcessor] Done org.jboss.test.ws.jaxws.samples.dar.DarRequest@1c2cbee
+11:31:42,311 INFO [STDOUT] ReplyTo sink:
+11:31:42,314 INFO [STDOUT] <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://www.w3.org/2005/08/addressing'><wsa:To>http://localhost:8080/dar-client/replyTo</wsa:To><wsa:Action>http://org.jboss.ws/samples/dar/DarEndpointPort/OUT</wsa:Action><wsa:RelatesTo>urn:uuid:321dee7b-953c-4405-9b06-dbc6743d36e6</wsa:RelatesTo></env:Header><env:Body><ns1:processResponse xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId></routes><routes><busId>Bus0</busId><stops><node>582</node><time>2008-02-05T11:31:36.443+01:00</time></stops><stops><node>662</node><time>2008-02-05T11:31:36.443+01:00</time></stops><stops><node>260</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node!
>962</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>10</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>959</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>138</node><time>2008-02-05T11:31:36.444+01:00</time></stops><stops><node>722</node><time>2008-02-05T11:31:36.444+01:00</time></stops></routes><unservedRequests><from><node>425</node><time>2008-02-05T11:31:36.443+01:00</time></from><id>Req0</id><people>2</people><to><node>920</node><time>2008-02-05T11:31:36.443+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope>
+
+11:31:42,362 INFO [STDOUT] http://localhost:8080/dar-client/replyTo
+11:31:42,362 INFO [DarProcessor] Processing DAR request... org.jboss.test.ws.jaxws.samples.dar.DarRequest@807653
+11:31:42,362 INFO [DarProcessor] 3 person(s) from 89 to 328
+11:31:42,362 INFO [DarProcessor] 1 person(s) from 293 to 743
+11:31:42,362 INFO [DarProcessor] 3 person(s) from 651 to 371
+11:31:42,362 INFO [DarProcessor] 2 person(s) from 283 to 326
+11:31:47,363 INFO [DarProcessor] Done org.jboss.test.ws.jaxws.samples.dar.DarRequest@807653
+11:31:47,374 INFO [STDOUT] ReplyTo sink:
+11:31:47,374 INFO [STDOUT] <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header xmlns:wsa='http://www.w3.org/2005/08/addressing'><wsa:To>http://localhost:8080/dar-client/replyTo</wsa:To><wsa:Action>http://org.jboss.ws/samples/dar/DarEndpointPort/OUT</wsa:Action><wsa:RelatesTo>urn:uuid:b9076402-f52-4aca-9e5b-b6e80cf1c3e2</wsa:RelatesTo></env:Header><env:Body><ns1:processResponse xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId><stops><node>283</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>326</node><time>2008-02-05T11:31:42.341+01:00</time></stops></routes><routes><busId>Bus0</busId><stops><node>89</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node&g!
t;328</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>293</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>743</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>651</node><time>2008-02-05T11:31:42.341+01:00</time></stops><stops><node>371</node><time>2008-02-05T11:31:42.341+01:00</time></stops></routes><unservedRequests><from><node>205</node><time>2008-02-05T11:31:42.341+01:00</time></from><id>Req0</id><people>1</people><to><node>630</node><time>2008-02-05T11:31:42.341+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope>
+
+11:31:47,527 INFO [DarAddressingEndpoint] AsyncProcessRequest sent...
+11:31:47,538 INFO [DarProcessor] Processing DAR request... org.jboss.test.ws.jaxws.samples.dar.DarRequest@149f848
+11:31:47,538 INFO [DarProcessor] 1 person(s) from 209 to 184
+11:31:47,538 INFO [DarProcessor] 2 person(s) from 167 to 524
+11:31:47,538 INFO [DarProcessor] 2 person(s) from 805 to 883
+11:31:47,538 INFO [DarProcessor] 1 person(s) from 101 to 224
+11:31:52,539 INFO [DarProcessor] Done org.jboss.test.ws.jaxws.samples.dar.DarRequest@149f848
+11:31:52,549 INFO [DarMessageBean] Response will be sent to: http://localhost:8080/dar-client/replyService
+11:31:52,887 INFO [DarReplyEndpointImpl] Result received; relationship message id: urn:uuid:cc5d90d1-d95-450d-a0cc-3a025f49d6c3
+11:31:52,888 INFO [DarReplyEndpointImpl] Bus1:
+11:31:52,888 INFO [DarReplyEndpointImpl] 209 184 101 224
+11:31:52,888 INFO [DarReplyEndpointImpl] Bus0:
+11:31:52,888 INFO [DarReplyEndpointImpl] 167 524 805 883
+11:31:52,890 INFO [DarMessageBean] Response sent.
+</screen><para>As you can see in the first and second invocations, simply having added the use of the addressing <emphasis>replyTo</emphasis> properties cause the response to be received from the sink servlet on the server side; however the client nevertheless hangs until the response is produced and sent.</para><para>The third run, using the couple of oneway invocations, shows how the client is free almost immediately after the request has been sent; the response is received through the <emphasis>DarReplyEndpointImpl</emphasis> 5 seconds later. For this reason the latter solution proves to be the best one, even if it requires more development.</para><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-Asynchronousinvocationssample_JMS_Endpoint"><title>JMS Endpoint</title><para>The JBossWS stack also allows you to obtain a JMS endpoint exposing message driven beans as web services. This gives us another way of performing the asynchronous invocation required for the DaR sample.</para><para> </para><section id="JBossWS-Asynchronousinvocationssample_The_service_endpoint"><title>The service endpoint</title><para>We use a bottom-up approach, thus we start coding an EJB3 message driven bean that extends <emphasis>org.jboss.ws.core.transport.jms.JMSTransportSupportEJB3</emphasis>; to make it a web service endpoint we use the usual annotations (@WebService, @WebMethod, etc.). Please note that even if we didn't do this here, you can fine tune the message consumption configuration like for any other message driven bean.</para><screen xml:space="preserve">@WebService (name = "DarEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/dar",
+ serviceName = "DarService")
+@WebContext(contextRoot="/dar")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+@MessageDriven(activationConfig = {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/DarRequestQueue")
+ },
+ messageListenerInterface = javax.jms.MessageListener.class
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarJMSEndpoint <emphasis role="bold">extends</emphasis> JMSTransportSupportEJB3
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> Logger log = Logger.getLogger(DarJMSEndpoint.class);
+
+ @WebMethod(operationName = "process", action = "http://org.jboss.test.ws.jaxws.samples.dar/action/processIn")
+ <emphasis role="bold">public</emphasis> DarResponse process(DarRequest request)
+ {
+ DarProcessor processor = <emphasis role="bold">new</emphasis> DarProcessor();
+ <emphasis role="bold">return</emphasis> processor.process(request);
+ }
+
+ @Override
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> onMessage(Message message)
+ {
+ log.debug("onMessage: " + message);
+ super.onMessage(message);
+ }
+}
+</screen><para>Once this simple endpoint is ready, you can build the project and take a look at the generated archive:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-jms.jar
+ 0 Fri Feb 01 17:55:20 CET 2008 META-INF/
+ 106 Fri Feb 01 17:55:18 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 789 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Bus.class
+ 2318 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarJMSEndpoint.class
+ 4231 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarProcessor.class
+ 1585 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarRequest.class
+ 1340 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarResponse.class
+ 1085 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Route.class
+ 1314 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/ServiceRequest.class
+ 834 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/Stop.class
+</screen><para>Nothing special, the JMS endpoint and the DaR model classes. The JBossWS stack automatically generates the wsdl contract at deploy time and publishes it for http use. We are however going to use this endpoint through JMS...</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_The_service_client"><title>The service client</title><para>The JMS client could be everything able to write to a JMS queue (here <emphasis>queue/DarRequestQueue</emphasis> on the server running the endpoint described above). In this sample the client is obtained through a simple servlet:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> JMSClient <emphasis role="bold">extends</emphasis> HttpServlet
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(JMSClient.class);
+
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> doGet(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) <emphasis role="bold">throws</emphasis> ServletException, IOException {
+ runMessageClient(<emphasis role="bold">new</emphasis> PrintStream(httpServletResponse.getOutputStream()));
+ }
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">void</emphasis> runMessageClient(PrintStream ps)
+ {
+ String reqMessage = "<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>" +
+ "<env:Header></env:Header>" +
+ "<env:Body>" +
+ "<ns1:process xmlns:ns1='http://org.jboss.ws/samples/dar'>" +
+ ...
+ "</ns1:process>" +
+ "</env:Body>" +
+ "</env:Envelope>";
+
+ QueueConnection con = <emphasis role="bold">null</emphasis>;
+ QueueSession session = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis>
+ {
+ InitialContext context = <emphasis role="bold">new</emphasis> InitialContext();
+ QueueConnectionFactory connectionFactory = (QueueConnectionFactory)context.lookup("ConnectionFactory");
+ Queue reqQueue = (Queue)context.lookup("queue/DarRequestQueue");
+ con = connectionFactory.createQueueConnection();
+ session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+ Queue resQueue = (Queue)context.lookup("queue/DarResponseQueue");
+ con.start();
+ TextMessage message = session.createTextMessage(reqMessage);
+ message.setJMSReplyTo(resQueue);
+ QueueSender sender = session.createSender(reqQueue);
+ sender.send(message);
+ sender.close();
+ ps.println("Request message sent, doing something interesting in the mean time... ;-) ");
+ con.stop();
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace(ps);
+ }
+ <emphasis role="bold">finally</emphasis>
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ session.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ <emphasis role="bold">try</emphasis>
+ {
+ con.close();
+ }
+ <emphasis role="bold">catch</emphasis>(Exception e1) {}
+ }
+ }
+
+
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> doPost(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) <emphasis role="bold">throws</emphasis> ServletException, IOException {
+ doGet(httpServletRequest,httpServletResponse);
+ }
+}
+</screen><para>The reason for using a servlet here instead of a standalone java application we could launch through wsrunclient, is that running in the container makes the queue connection factory lookup much easier. Of course you can do this in another way.</para><para> </para><para>As you can see, the client specifies the response queue where the server has to reply, <emphasis>queue/DarResponseQueue</emphasis>, thus we'll need to define a message listener to get the responses from it.</para><para> </para><para>To invoke the JMS endpoint, we could have of course done like <ulink url="http://community.jboss.org/docs/DOC-13972#JMS_Transport_Clients">what is shown in the JAX-WS guide</ulink>: manually add a port binding with a jms soap:address to the wsdl contract and invoke the endpoint as we would do for standard http invocations. This however is useless in cases like ours, since the invocation fails if the reply doesn't come within a short time period and the client hang!
s until the the response arrives or the timeout expires. So let's define our message listener:</para><screen xml:space="preserve">@MessageDriven(activationConfig = {
+ @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination", propertyValue = "queue/DarResponseQueue")
+ },
+ messageListenerInterface = javax.jms.MessageListener.class
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DarResponseMessageBean
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(DarResponseMessageBean.class);
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> onMessage(Message arg0)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ TextMessage textMessage = (TextMessage)arg0;
+ String result = textMessage.getText();
+ log.info("DAR response received: " + result);
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>It's another message driven bean that listens on <emphasis>queue/DarResponseQueue</emphasis> and simply logs the received messages.</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_Running_the_sample_802346"><title>Running the sample</title><para>Now it's time to run the sample; we already built and deployed the server side (<emphasis>jaxws-samples-dar-jms.jar</emphasis>), thus let's take a look at the generated client archives first. You'll get a <emphasis>sar</emphasis> file containing two archives: the first one (<emphasis>jaxws-samples-dar-jms-client.war</emphasis>) is the invocation part of the client, containing the servlet...</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-jms-client.war
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 01 19:34:22 CET 2008 WEB-INF/
+ 625 Fri Feb 01 14:11:00 CET 2008 WEB-INF/web.xml
+ 0 Thu Jan 10 21:41:02 CET 2008 WEB-INF/classes/org/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 WEB-INF/classes/org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/
+ 4407 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/ClientHelper.class
+ 4560 Fri Feb 01 19:34:10 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/JMSClient.class
+ 0 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/
+ 1017 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Bus.class
+ 1447 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarEndpoint.class
+ 1619 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarRequest.class
+ 1389 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarResponse.class
+ 1597 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/DarService.class
+ 1681 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/ObjectFactory.class
+ 1267 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Route.class
+ 1589 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/ServiceRequest.class
+ 1210 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/Stop.class
+ 282 Fri Feb 01 17:55:08 CET 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/dar/generated/package-info.class
+ 232 Fri Feb 01 14:11:00 CET 2008 WEB-INF/jboss-web.xml
+</screen><para>... the second one (<emphasis>jaxws-samples-dar-jms-client.jar</emphasis>) ships the response message bean instead:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-jms-client.jar
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 0 Thu Jan 10 21:41:02 CET 2008 org/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/
+ 0 Thu Jan 10 21:07:24 CET 2008 org/jboss/test/
+ 0 Thu Jan 10 21:41:22 CET 2008 org/jboss/test/ws/
+ 0 Tue Jan 29 15:37:30 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 01 17:55:08 CET 2008 org/jboss/test/ws/jaxws/samples/dar/
+ 1513 Fri Feb 01 19:34:10 CET 2008 org/jboss/test/ws/jaxws/samples/dar/DarResponseMessageBean.class
+</screen><para>Here is the <emphasis>jaxws-samples-dar-jms-client.sar</emphasis> archive:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-dar-jms-client.sar
+ 0 Fri Feb 01 19:34:22 CET 2008 META-INF/
+ 106 Fri Feb 01 19:34:20 CET 2008 META-INF/MANIFEST.MF
+ 2156 Fri Feb 01 19:34:22 CET 2008 jaxws-samples-dar-jms-client.jar
+ 14138 Fri Feb 01 19:34:22 CET 2008 jaxws-samples-dar-jms-client.war
+ 58 Fri Feb 01 17:47:20 CET 2008 META-INF/jboss-service.xml
+</screen><para>As you can see from the sources, the <emphasis>jboss-service.xml</emphasis> doesn't define anything actually; it could be used to install the two queue we use, but since the application server automatically creates the queues any MDB listens to, we choose the easy way here.</para><para> </para><para>Finally we can run the sample! Please drop the <emphasis>sar</emphasis> archive in the deploy directory of you already running application server, then just browse to <ulink url="http://localhost:8080/dar-jms-client/JMSClient">http://localhost:8080/dar-jms-client/JMSClient</ulink>: you'll immediately get a simple page saying the request has been sent, meaning the invocation part of the client did his job. On the logs you'll see something like this:</para><screen xml:space="preserve">10:13:47,279 INFO [DarProcessor] Processing DAR request... org.jboss.test.ws.jaxws.samples.dar.DarRequest@694b7e
+10:13:47,279 INFO [DarProcessor] 1 person(s) from 18 to 575
+10:13:47,279 INFO [DarProcessor] 2 person(s) from 713 to 845
+10:13:47,279 INFO [DarProcessor] 2 person(s) from 117 to 140
+10:13:47,279 INFO [DarProcessor] 1 person(s) from 318 to 57
+10:13:52,280 INFO [DarProcessor] Done org.jboss.test.ws.jaxws.samples.dar.DarRequest@694b7e
+10:13:52,353 INFO [AbstractJMSTransportSupport] Sent response
+10:13:52,360 INFO [DarResponseMessageBean] DAR response received: <env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header></env:Header><env:Body><ns1:processResponse xmlns:ns1='http://org.jboss.ws/samples/dar'><return><routes><busId>Bus1</busId><stops><node>117</node></stops><stops><node>140</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>318</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>57</node><time>2008-02-01T14:25:12.114+01:00</time></stops></routes><routes><busId>Bus0</busId><stops><node>18</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>575</node><time>2008-02-01T14:25:12.114+01:00</time></stops><s!
tops><node>713</node><time>2008-02-01T14:25:12.114+01:00</time></stops><stops><node>845</node><time>2008-02-01T14:25:12.114+01:00</time></stops></routes><unservedRequests><from><node>667</node><time>2008-02-01T14:25:12.114+01:00</time></from><id>Req0</id><people>2</people><to><node>17</node><time>2008-02-01T14:25:12.114+01:00</time></to></unservedRequests></return></ns1:processResponse></env:Body></env:Envelope></screen><para>Once the DaR request processing is done, the response is put to the queue and the <emphasis>DarResponseMessageBean</emphasis> consumes it. We achieved the expected behavior using the JMS transport too, however...</para><para> </para></section>
+<section id="JBossWS-Asynchronousinvocationssample_Client_and_server_on_different_boxes"><title>Client and server on different boxes</title><para>As previously said, for ease we've been deploying both client and server sides of our application on the same JBoss instance. We all know that web services are about different systems interoperability thus running client and server on different boxes is the common situation. However obtaining this is not straightforward when playing with queues and message bean endpoints. The reason for this is that both the request and response queue belong to the service provider side, even if the client says which response queue has to be used. A real world architecture with client and server running on different boxes implies that:</para><itemizedlist><listitem><para> you need to define the response queue on the server side, using a <emphasis>jboss-service.xml</emphasis> descriptor: </para></listitem></itemizedlist><screen xml:space="preserve"!
><?xml version="1.0" encoding="UTF-8"?>
+<server>
+ <mbean code="org.jboss.mq.server.jmx.Queue" name="jboss.mq.destination:service=Queue,name=DarResponseQueue">
+ <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+</server>
+</screen><para>Note if you're running on JBoss5 and above, you need to define both request and response queues using <emphasis>jboss-service.xml</emphasis> descriptor:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<server>
+ <mbean code="org.jboss.mq.server.jmx.Queue" name="jboss.mq.destination:service=Queue,name=DarRequestQueue">
+ <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+ <mbean code="org.jboss.mq.server.jmx.Queue" name="jboss.mq.destination:service=Queue,name=DarResponseQueue">
+ <depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
+ </mbean>
+</server>
+</screen><itemizedlist><listitem><para> when sending the request, your client has to lookup the queue using the remote provider; this is achieved properly configuring the InitialContext: </para></listitem></itemizedlist><screen xml:space="preserve">Hashtable env = <emphasis role="bold">new</emphasis> Hashtable();
+env.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
+env.put("java.naming.factory.url.pkgs","org.jboss.naming:org.jnp.interfaces");
+env.put(javax.naming.Context.PROVIDER_URL, service_provider_host_address);
+InitialContext context = <emphasis role="bold">new</emphasis> InitialContext(env);
+QueueConnectionFactory connectionFactory = (QueueConnectionFactory)context.lookup("ConnectionFactory");
+Queue reqQueue = (Queue)context.lookup("queue/DarRequestQueue");
+con = connectionFactory.createQueueConnection();
+session = con.createQueueSession(false, Session.AUTO_ACKNOWLEDGE);
+Queue resQueue = (Queue)context.lookup("queue/DarResponseQueue");
+</screen><itemizedlist><listitem><para> if you want to stick to the solution using the client response message bean, it has to listen to a remote queue. The instruction for doing so are available at the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=HowDoIConfigureAnEJB3MDBToTalkTo...">main JBoss wiki</ulink> </para></listitem><listitem><para> finally, you'll have to cope with the need of defining and advertising different response queues for each service consumer, which might not be that good... </para></listitem></itemizedlist></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Authentication.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Authentication.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Authentication.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Authentication"><title>JBossWS-Authentication</title><para>This page explains the simplest way to authenticate a web service user with JBossWS.</para><para>First we secure the access to the SLSB as we would do for normal (non web service) invocations: this can be easily done through the @RolesAllowed, @PermitAll, @DenyAll annotation. The allowed user roles can be set with these annotations both on the bean class and on any of its business methods.</para><screen xml:space="preserve">@Stateless
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly POJO endpoints are secured the same way as we do for normal web applications in web.xml:</para><screen xml:space="preserve"> <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role></screen><section><title>Define the security domain</title><para>Next, define the security domain for this deployment. This is performed using the <ulink url="http://community.jboss.org/docs/DOC-13972#SecurityDomain">@SecurityDomain</ulink> annotation for EJB3 endpoints</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>or modifying the jboss-web.xml for POJO endpoints</para><screen xml:space="preserve"><jboss-web>
+ <security-domain>java:/jaas/JBossWS</security-domain>
+</jboss-web>
+</screen><para>The JBossWS security context is configured in login-config.xml and uses the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsersRolesLoginModule">UsersRolesLoginModule</ulink>. As a matter of fact login-config.xml, that lives in the server config dir, contains this security domain definition:</para><screen xml:space="preserve"> <!--
+ A template configuration for the JBossWS security domain.
+ This defaults to the UsersRolesLoginModule the same as other and should be
+ changed to a stronger authentication mechanism as required.
+ -->
+ <application-policy name="JBossWS">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="usersProperties">props/jbossws-users.properties</module-option>
+ <module-option name="rolesProperties">props/jbossws-roles.properties</module-option>
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+</screen><para>Of course you can define and use your own security domain as well as your login module (in order to check for users' identity querying a database for example).</para></section>
+<section><title>Use BindingProvider to set principal/credential</title><para>A web service client may use the javax.xml.ws.BindingProvider interface to set the username/password combination</para><screen xml:space="preserve">URL wsdlURL = <emphasis role="bold">new</emphasis> File("resources/jaxws/samples/context/WEB-INF/wsdl/TestEndpoint.wsdl").toURL();
+QName qname = <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/jaxws/context", "TestEndpointService");
+Service service = Service.create(wsdlURL, qname);
+port = (TestEndpoint)service.getPort(TestEndpoint.class);
+
+BindingProvider bp = (BindingProvider)port;
+bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit");
+bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "thefrog");
+</screen></section>
+<section><title>Using HTTP Basic Auth for security</title><para>To enable HTTP Basic authentication you use the <ulink url="http://community.jboss.org/docs/DOC-13972#WebContext">@WebContext</ulink> annotation on the bean class</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext(contextRoot="/my-cxt", urlPattern="/*", authMethod="BASIC", transportGuarantee="NONE", secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>For POJO endpoints, we modify the web.xml adding the auth-method element:</para><screen xml:space="preserve"> <login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>Test Realm</realm-name>
+ </login-config>
+</screen></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Endpointmanagement.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Endpointmanagement"><title>JBossWS-Endpointmanagement</title><para>JBossWS registers MBeans that users can leverage to manage every webservice endpoint. Apart from the obvious start/stop functionalities, they provide valuable information and statistics about messages processed by the endpoints.</para><para/><para> </para><section id="JBossWS-Endpointmanagement_Getting_the_information"><title>Getting the information</title><para>JBoss ships with a JMX-Console with all the application server MBeans. It is usually available at URL <ulink url="http://localhost:8080/jmx-console">http://localhost:8080/jmx-console</ulink>. For endpoint management you might be interested in the MBeans belonging to the jboss.ws domain.</para><para>The application server also has an applet based web-console which basically has the same data as the JMX-Console plus some advanced features including snapshot graphics.</para><para>Of course!
you can access an MBean programmatically too. Please refer to the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=FAQJBossJMX">JBoss JMX faq</ulink> for further details; here is a brief code snippet you might want to start from in order to access a ManagedEndpointMBean from the same virtual machine:</para><screen xml:space="preserve"><emphasis role="bold">try</emphasis>
+{
+ MBeanServer server = MBeanServerLocator.locate();
+ ManagedEndpointMBean mep = (ManagedEndpointMBean)MBeanProxyExt.create(
+ ManagedEndpointMBean.class,
+ "jboss.ws:context=my-ctx,endpoint=MyEndpoit",
+ server);
+ ...
+}
+<emphasis role="bold">catch</emphasis> (Exception e)
+{
+ e.printStackTrace();
+}
+</screen></section>
+<section id="JBossWS-Endpointmanagement_Metrics"><title>Metrics</title><para>For each deployed endpoint you'll find an <emphasis>org.jboss.wsf.framework.management.ManagedEndpoint</emphasis> MBean providing basic start/stop functionalities and metrics. Calling a stopped endpoint will always result in a SOAP fault message.</para><para>The metrics available for each managed endpoint are:</para><itemizedlist><listitem><para> Min, max, average and total processing time: processing includes both the WS stack plus application server work and the user business logic </para></listitem><listitem><para> Last start and stop time </para></listitem><listitem><para> Request, response and fault count</para></listitem></itemizedlist></section>
+<section id="JBossWS-Endpointmanagement_Records"><title>Records</title><para>JBossWS features a highly configurable records' collection and management system. Each record is basically composed of a message plus additional information (for example the caller address and the called endpoint operation).</para><para>Endpoints can be configured with record processors that are invoked whenever a message flow is detected and records are thus created.</para><para>Every deployed endpoint is configured with default record processors. However custom processors as well as record filters can be easily plugged in and managed at any time through JMX. This gives users the chance of performing advanced analysis of the webservice traffic according to their business requirements.</para><para>Please refer to the <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Records_management">records management page</ulink> for further details.</para></section>
+<section id="JBossWS-Endpointmanagement_Snapshots_and_threshold_monitors"><title>Snapshots and threshold monitors</title><para>As previously said, the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsole">JBoss Web Console</ulink> has interesting features including <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleSnapshots">snapshots</ulink> and <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleMonitoring">threshold monitors</ulink>.</para><para>Snapshots allow users to record changes of a given MBean attribute within a defined time interval. Data are sampled at a given rate and may be plotted to graphs with a few clicks. Snapshots are listed in the Web console and can be created simply browsing to <ulink url="http://localhost:8080/web-console/createSnapshot.jsp">http://localhost:8080/web-console/createSnapshot.jsp</ulink> .</para><para>Threshold monitors allow users to be notified whenever a given MBean attribute exceed a certain range!
of values. The threshold monitor's creation and management processes are similar to those mentioned above for the snapshots. Simply browse to <ulink url="http://localhost:8080/web-console/createThresholdMonitor.jsp">http://localhost:8080/web-console/createThresholdMonitor.jsp</ulink> .</para><para>Speaking of WS availability and SLA, this all becomes interesting because users can monitor and take snapshots of critical attributes like the average/max processing time of a managed endpoint. Moreover, advanced analysis can be performed leveraging ad-hoc attributes of custom <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Endpoint_management#Re...">record processors</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSAnnotations"><title>JBossWS-JAX-WSAnnotations</title><para/><section id="JBossWS-JAX-WSAnnotations_JAXWS_Annotations"><title>JAX-WS Annotations</title><para>For details, see <ulink url="http://www.jcp.org/en/jsr/detail?id=224">JSR-224 - Java API for XML-Based Web Services (JAX-WS) 2.0</ulink></para><para> </para><section id="JBossWS-JAX-WSAnnotations_javaxxmlwsServiceMode"><title>javax.xml.ws.ServiceMode</title><para>The ServiceMode annotation is used to specify the mode for a provider class, i.e. whether a provider wants to have access to protocol message payloads (e.g. a SOAP body) or the entire protocol messages (e.g. a SOAP envelope).</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebFault"><title>javax.xml.ws.WebFault</title><para>The WebFault annotation is used when mapping WSDL faults to Java exceptions, see section 2.5. It is used to capture the name of the fault element used when marshalling the JAXB type generated from the global element referenced by the WSDL fault message. It can also be used to customize the mapping of service specific exceptions to WSDL faults.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsRequestWrapper"><title>javax.xml.ws.RequestWrapper</title><para>The RequestWrapper annotation is applied to the methods of an SEI. It is used to capture the JAXB generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. The default value of localName element is the operationName as defined in WebMethod annotation and the default value for the targetNamespace element is the target namespace of the SEI.When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsResponseWrapper"><title>javax.xml.ws.ResponseWrapper</title><para>The ResponseWrapper annotation is applied to the methods of an SEI. It is used to capture the JAXB generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. The default value of the localName element is the operationName as defined in the WebMethod appended with ”Response” and the default value of the targetNamespace element is the target namespace of the SEI. When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceClient"><title>javax.xml.ws.WebServiceClient</title><para>The WebServiceClient annotation is specified on a generated service class (see 2.7). It is used to associate a class with a specific Web service, identify by a URL to a WSDL document and the qualified name of a wsdl:service element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebEndpoint"><title>javax.xml.ws.WebEndpoint</title><para>The WebEndpoint annotation is specified on the getPortName() methods of a generated service class (see 2.7). It is used to associate a get method with a specific wsdl:port, identified by its local name (a NCName).</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceProvider"><title>javax.xml.ws.WebServiceProvider</title><para>The WebServiceProvider annotation is specified on classes that implement a strongly typed javax- .xml.ws.Provider. It is used to declare that a class that satisfies the requirements for a provider (see 5.1) does indeed define a Web service endpoint, much like the WebService annotation does for SEI-based endpoints.</para><para>The WebServiceProvider and WebService annotations are mutually exclusive.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsBindingType"><title>javax.xml.ws.BindingType</title><para>The BindingType annotation is applied to an endpoint implementation class. It specifies the binding to use when publishing an endpoint of this type.</para><para>The default binding for an endpoint is the SOAP 1.1/HTTP one</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRef"><title>javax.xml.ws.WebServiceRef</title><para>The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250 [32]. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform, where it is subject to the common resource injection rules described by the platform specification [33].</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRefs"><title>javax.xml.ws.WebServiceRefs</title><para>The WebServiceRefs annotation is used to declare multiple references to Web services on a single class. It is necessary to work around the limition against specifying repeated annotations of the same type on any given class, which prevents listing multiple javax.ws.WebServiceRef annotations one after the other. This annotation follows the resource pattern exemplified by the javax.annotation.Resources annotation in JSR-250.</para><para>Since no name and type can be inferred in this case, each WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with non-default values. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform, where it is subject to the common resource injection rules described by the platform specification.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsAction"><title>javax.xml.ws.Action</title><para>The Action annotation is applied to the methods of a SEI. It used to generate the wsa:Action on wsdl:input and wsdl:output of each wsdl:operation mapped from the annotated methods.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsFaultAction"><title>javax.xml.ws.FaultAction</title><para>The FaultAction annotation is used within the Action annotation to generate the wsa:Action element on the wsdl:fault element of each wsdl:operation mapped from the annotated methods.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_Annotations_Defined_by_JSR181"><title>Annotations Defined by JSR-181</title><para>JSR-181 defines the syntax and semantics of Java Web Service (JWS) metadata and default values.</para><para>For details, see <ulink url="http://jcp.org/en/jsr/detail?id=181">JSR 181 - Web Services Metadata for the Java Platform</ulink></para><para> </para><section id="JBossWS-JAX-WSAnnotations_javaxjwsWebService"><title>javax.jws.WebService</title><para>Marks a Java class as implementing a Web Service, or a Java interface as defining a Web Service interface.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebMethod"><title>javax.jws.WebMethod</title><para>Customizes a method that is exposed as a Web Service operation.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsOneWay"><title>javax.jws.OneWay</title><para>Indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method. A JSR-181 processor is REQUIRED to report an error if an operation marked @Oneway has a return value, declares any checked exceptions or has any INOUT or OUT parameters.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebParam"><title>javax.jws.WebParam</title><para>Customizes the mapping of an individual parameter to a Web Service message part and XML element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebResult"><title>javax.jws.WebResult</title><para>Customizes the mapping of the return value to a WSDL part and XML element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsSOAPBinding"><title>javax.jws.SOAPBinding</title><para>Specifies the mapping of the Web Service onto the SOAP message protocol.</para><para>The SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC. Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsHandlerChain"><title>javax.jws.HandlerChain</title><para>The @HandlerChain annotation associates the Web Service with an externally defined handler chain.</para><para>It is an error to combine this annotation with the @SOAPMessageHandlers annotation.</para><para>The @HandlerChain annotation MAY be present on the endpoint interface and service implementation bean. The service implementation bean's @HandlerChain is used if @HandlerChain is present on both.</para><para>The @HandlerChain annotation MAY be specified on the type only. The annotation target includes METHOD and FIELD for use by JAX-WS-2.0.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSClientConfiguration.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSClientConfiguration"><title>JBossWS-JAX-WSClientConfiguration</title><para/><para> </para><para>The standard client configuration is defined in <emphasis role="bold">standard-jaxws-client-config.xml</emphasis></para><para> </para><section id="JBossWS-JAX-WSClientConfiguration_Client_side_port_configuration"><title>Client side port configuration</title><para>You can use stub properties on the client side to chose from one of the configuration presets:</para><screen xml:space="preserve"> Hello endpoint = service.getPort(Hello.class);
+((StubExt) endpoint).setConfigName("Standard WSSecurity Client");
+</screen><para> </para></section>
+<section id="JBossWS-JAX-WSClientConfiguration_Available_configuration"><title>Available configuration</title><section id="JBossWS-JAX-WSClientConfiguration_Standard_Client"><title>Standard Client</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard Client</config-name>
+ </client-config></jaxws-config>]</screen><para><anchor id="Standard_WSAddressing_Client">#</anchor></para></section>
+<section id="JBossWS-JAX-WSClientConfiguration_Standard_WSAddressing_Client"><title>Standard WSAddressing Client</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard WSAddressing Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config></screen><para> </para></section>
+<section id="JBossWS-JAX-WSClientConfiguration_Standard_SOAP_12_WSAddressing_Client_Since_203_Native"><title>Standard SOAP 1.2 WSAddressing Client Since 2.0.3 (Native)</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard SOAP 1.2 WSAddressing Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config></screen></section>
+<section id="JBossWS-JAX-WSClientConfiguration_Standard_WSSecurity_Client"><title>Standard WSSecurity Client</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard WSSecurity Client</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSSecurityHandlerOutbound</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.security.jaxws.WSSecurityHandlerClient</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSEndpointConfiguration.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSEndpointConfiguration"><title>JBossWS-JAX-WSEndpointConfiguration</title><para/><para> </para><para>The standard endpoint configuration is defined in <emphasis role="bold">standard-jaxws-endpoint-config.xml</emphasis></para><para> </para><section id="JBossWS-JAX-WSEndpointConfiguration_Using_EndpointConfig"><title>Using @EndpointConfig</title><para>On the server side you proabably use the <computeroutput>@EndpointConfig</computeroutput> annotation to specify one of the available (might be custom as well) configurations:</para><screen xml:space="preserve">@WebService(name = "Hello", serviceName = "HelloService", targetNamespace = "http://org.jboss.ws/samples/wssecurity")
+@EndpointConfig(configName = "Standard WSSecurity Endpoint") (1)
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><orderedlist><listitem><para> @EndpointConfig(configName = "Standard WSSecurity Endpoint")</para></listitem></orderedlist><para> </para><para> </para></section>
+<section id="JBossWS-JAX-WSEndpointConfiguration_Configuration_presets"><title>Configuration presets</title><section id="JBossWS-JAX-WSEndpointConfiguration_Standard_Endpoint"><title>Standard Endpoint</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard Endpoint</config-name>
+ </endpoint-config></jaxws-config></screen></section>
+<section id="JBossWS-JAX-WSEndpointConfiguration_Standard_WSAddressing_Endpoint"><title>Standard WSAddressing Endpoint</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSAddressing Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-JAX-WSEndpointConfiguration_Standard_SOAP_12_WSAddressing_Endpoint_Since_203_Native"><title>Standard SOAP 1.2 WSAddressing Endpoint Since 2.0.3 (Native)</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard SOAP 1.2 WSAddressing Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP12_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config></screen></section>
+<section id="JBossWS-JAX-WSEndpointConfiguration_Standard_WSSecurity_Endpoint"><title>Standard WSSecurity Endpoint</title><screen xml:space="preserve"><jaxws-config xmlns="urn:jboss:jaxws-config:2.0" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>" xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSSecurity Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSSecurity Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.security.jaxws.WSSecurityHandlerServer</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-JAX-WSTools.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSTools"><title>JBossWS-JAX-WSTools</title><para>The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look at server-side development strategies, and then proceed to the client.</para><para/><section id="JBossWS-JAX-WSTools_Server_side"><title>Server side</title><para>When developing a Web Service Endpoint (the server-side) you have the option of starting from Java (bottom-up development), or from the abstact contract (WSDL) that defines your service (top-down development). If this is a new service (no existing contract), the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with an already defined contract, it is far simpler to use the top-down approach, since the provided tool will generate the annotated code for you.</para><para>Bottom-up use cases:</para!
><itemizedlist><listitem><para> Exposing an already existing EJB3 bean as a Web Service </para></listitem><listitem><para> Providing a new service, and you want the contract to be generated for you </para></listitem></itemizedlist><para>Top-down use cases:</para><itemizedlist><listitem><para> Replacing the implementation of an existing Web Service, and you can't break compatibility with older clients </para></listitem><listitem><para> Exposing a service that conforms to a contract specified by a third party (e.g. a vender that calls you back using an already defined protocol). </para></listitem><listitem><para> Creating a service that adheres to the XML Schema and WSDL you developed by hand up front </para></listitem></itemizedlist><para>The following JAX-WS command line tools are included in JBossWS:</para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> Command </entry><entry> Description </entry><!
/row></thead><tbody><row><entry><para><link linkend="chap_JBos!
sWS-wspr
ovide">JBossWS - wsprovide</link></para></entry><entry>Generates JAX-WS portable artifacts, and provides the abstract contract. Used for bottom-up development.</entry></row><row><entry><para><link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link></para></entry><entry>Consumes the abstract contract (WSDL and Schema files), and produces artifacts for both a server and client. Used for top-down and client development</entry></row><row><entry><para><link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link></para></entry><entry>Executes a Java client (has a main method) using the JBossWS classpath.</entry></row></tbody></tgroup></informaltable><section id="JBossWS-JAX-WSTools_BottomUp_Using_wsprovide"><title>Bottom-Up (Using wsprovide)</title><para>The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service!
. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required.</para><para>This can be as simple as creating a single class:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ <emphasis role="bold">return</emphasis> input;
+ }
+}
+</screen><para>A JSE or EJB3 deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper classes" will be generated for you at deploy time. This actually goes beyond the JAX-WS specification, which requires that wrapper classes be generated using an offline tool. The reason for this requirement is purely a vender implementation problem, and since we do not believe in burdening a developer with a bunch of additional steps, we generate these as well. However, if you want your deployment to be portable to other application servers, you will unfortunately need to use a tool and add the generated classes to your deployment.</para><para>This is the primary purpose of the <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obt!
ained by invoking <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link> using the "-w" option:</para><screen xml:space="preserve">$ javac -d . -classpath jboss-jaxws.jar Echo.java
+$ wsprovide -w echo.Echo
+Generating WSDL:
+EchoService.wsdl
+Writing Classes:
+echo/jaxws/Echo.class
+echo/jaxws/EchoResponse.class
+</screen><para>Inspecting the WSDL reveals a service called EchoService:</para><screen xml:space="preserve"><service name='EchoService'><port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/></port>
+</service>
+</screen><para>As expected, this service defines one operation, "echo":</para><screen xml:space="preserve"><portType name='Echo'><operation name='echo' parameterOrder='echo'>
+ <input message='tns:Echo_echo'/>
+ <output message='tns:Echo_echoResponse'/></operation>
+</portType>
+</screen><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>Remember that <emphasis role="bold">when deploying on JBossWS you do not need to run this tool.</emphasis> You only need it for generating portable artifacts and/or the abstract contract for your service.</emphasis></para></para></note><para>Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be created:</para><screen xml:space="preserve"><web-app xmlns="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink> <ulink url="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd</ulink>"
+ version="2.4">
+
+ <servlet>
+ <servlet-name>Echo</servlet-name>
+ <servlet-class>echo.Echo</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>Echo</servlet-name>
+ <url-pattern>/Echo</url-pattern>
+ </servlet-mapping>
+</web-app>
+</screen><para>The web.xml and the single class can now be used to create a war:</para><screen xml:space="preserve">$ mkdir -p WEB-INF/classes
+$ cp -rp echo WEB-INF/classes/
+$ cp web.xml WEB-INF
+$ jar cvf echo.war WEB-INF
+added manifest
+adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
+adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
+</screen><para>The war can then be deployed:</para><screen xml:space="preserve">cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
+</screen><para>This will internally invoke <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>, which will generate the WSDL. If deployment was successful, and you are using the default settings, it should be available here: <ulink url="http://localhost:8080/echo/Echo?wsdl">http://localhost:8080/echo/Echo?wsdl</ulink></para><para>For a portable JAX-WS deployment, the wrapper classes generated earlier could be added to the deployment.</para></section>
+<section id="JBossWS-JAX-WSTools_TopDown_Using_wsconsume"><title>Top-Down (Using wsconsume)</title><para>The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> tool is then used to consume this contract, and produce annotated Java classes (and optionally sources) that define it.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>wsconsume seems to have a problem with symlinks on unix systems</para></para></note><para>Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The "-k" option is passed to <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> to preserve the Java source files that are generated, instead of providing just classes:</para><screen xml:space="preserve">
+$ wsconsume -k EchoService.wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</screen><para>The following table shows the purpose of each generated file:</para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> File </entry><entry> Purpose </entry></row></thead><tbody><row><entry>Echo.java</entry><entry>Service Endpoint Interface</entry></row><row><entry>Echo_Type.java</entry><entry>Wrapper bean for request message</entry></row><row><entry>EchoResponse.java</entry><entry>Wrapper bean for response message</entry></row><row><entry>ObjectFactory.java</entry><entry>JAXB XML Registry</entry></row><row><entry>package-info.java</entry><entry>Holder for JAXB package annotations</entry></row><row><entry>EchoService.java</entry><entry>Used only by JAX-WS clients</entry></row></tbody></tgroup></informaltable><para>Examining the Service Endpoint Interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example, however, these evaluate to the sa!
me contract:</para><screen xml:space="preserve">@WebService(name = "Echo", targetNamespace = "http://echo/")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> Echo {
+ @WebMethod
+ @WebResult(targetNamespace = "")
+ @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
+ @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
+ <emphasis role="bold">public</emphasis> String echo(
+ @WebParam(name = "arg0", targetNamespace = "")
+ String arg0);
+
+}
+</screen><para>The only missing piece (besides the packaging) is the implementation class, which can now be written, using the above interface.</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService(endpointInterface="echo.Echo")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoImpl <emphasis role="bold">implements</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String arg0)
+ {
+ <emphasis role="bold">return</emphasis> arg0;
+ }
+}
+</screen></section>
+</section>
+<section id="JBossWS-JAX-WSTools_Client_Side"><title>Client Side</title><para>Before going to detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way. There are much better technologies for this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular OS, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the!
<emphasis><emphasis role="bold">recommended methodology for developing a client is</emphasis></emphasis> to follow <emphasis><emphasis role="bold">the top-down approach</emphasis></emphasis>, even if the client is running on the same server.</para><para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para><para>Offline version:</para><screen xml:space="preserve"><service name='EchoService'>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</screen><para>Online version:</para><screen xml:space="preserve"><service name="EchoService">
+ <port binding="tns:EchoBinding" name="EchoPort">
+ <soap:address location="<ulink url="http://localhost.localdomain:8080/echo/Echo">http://localhost.localdomain:8080/echo/Echo</ulink>"/>
+ </port>
+</service>
+</screen><para>Using the online deployed version with <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link>:</para><screen xml:space="preserve">$ wsconsume -k http://localhost:8080/echo/Echo?wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</screen><para>The one class that was not examined in the top-down section, was EchoService.java. Notice how it stores the location the WSDL was obtained from.</para><screen xml:space="preserve">@WebServiceClient(name = "EchoService", targetNamespace = "http://echo/", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoService <emphasis role="bold">extends</emphasis> Service
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">static</emphasis> URL ECHOSERVICE_WSDL_LOCATION;
+
+ <emphasis role="bold">static</emphasis> {
+ URL url = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis> {
+ url = <emphasis role="bold">new</emphasis> URL("http://localhost:8080/echo/Echo?wsdl");
+ } <emphasis role="bold">catch</emphasis> (MalformedURLException e) {
+ e.printStackTrace();
+ }
+ ECHOSERVICE_WSDL_LOCATION = url;
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService(URL wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService() {
+ <emphasis role="bold">super</emphasis>(ECHOSERVICE_WSDL_LOCATION, <emphasis role="bold">new</emphasis> QName("http://echo/", "EchoService"));
+ }
+
+ @WebEndpoint(name = "EchoPort")
+ <emphasis role="bold">public</emphasis> Echo getEchoPort() {
+ <emphasis role="bold">return</emphasis> (Echo)super.getPort(<emphasis role="bold">new</emphasis> QName("http://echo/", "EchoPort"), Echo.class);
+ }
+}
+</screen><para>As you can see, this generated class extends the main client entry point in JAX-WS, javax.xml.ws.Service. While you can use Service directly, this is far simpler since it provides the configuration info for you. The only method we really care about is the getEchoPort() method, which returns an instance of our Service Endpoint Interface. Any WS operation can then be called by just invoking a method on the returned interface.</para><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>It's not recommended to refer to a remote WSDL URL in a production application. This causes network I/O every time you instantiate the Service Object. Instead, use the tool on a saved local copy, or use the URL version of the constructor to provide a new WSDL location.</emphasis></para></para></note><para>All that is left to do, is write and compile the client:</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> e!
cho.*;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoClient
+{
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String args[])
+ {
+ <emphasis role="bold">if</emphasis> (args.length != 1)
+ {
+ System.err.println("usage: EchoClient <message>");
+ System.exit(1);
+ }
+
+ EchoService service = <emphasis role="bold">new</emphasis> EchoService();
+ Echo echo = service.getEchoPort();
+ System.out.println("Server said: " + echo.echo(args[0]));
+ }}
+</screen><para>It can then be easily executed using the <link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link> tool. This is just a convenience tool that invokes java with the needed classpath:</para><screen xml:space="preserve">$ wsrunclient EchoClient 'Hello World!'
+Server said: Hello World!
+</screen><para>It is easy to change the endpoint address of your operation at runtime, setting the ENDPOINT_ADDRESS_PROPERTY as shown below:</para><screen xml:space="preserve">...
+ EchoService service = <emphasis role="bold">new</emphasis> EchoService();
+ Echo echo = service.getEchoPort();
+
+ /* Set NEW Endpoint Location */
+ String endpointURL = "http://NEW_ENDPOINT_URL";
+ BindingProvider bp = (BindingProvider)echo;
+ bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
+
+ System.out.println("Server said: " + echo.echo(args[0]));
+...
+</screen></section>
+<section id="JBossWS-JAX-WSTools_Commandline_Maven_Plugin_and_Ant_Task_Reference"><title>Command-line, Maven Plugin and Ant Task Reference</title><itemizedlist><listitem><para> <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> reference page </para></listitem><listitem><para> <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link> reference page </para></listitem><listitem><para> <link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link> reference page</para></listitem></itemizedlist></section>
+<section id="JBossWS-JAX-WSTools_JAXWS_binding_customization"><title>JAX-WS binding customization</title><para>An introduction to binding customizations:</para><itemizedlist><listitem><para> <ulink url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html">http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html</ulink> </para></listitem><listitem><para> <ulink url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...">binding schema</ulink> </para></listitem><listitem><para> <ulink url="https://jax-ws.dev.java.net/nonav/guide/customizations/">xnsdoc</ulink> </para></listitem></itemizedlist><para>The schema for the binding customization files can be found here:</para><itemizedlist><listitem><para> <ulink url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...">https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...!
2&view=log</ulink> </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Native.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Native.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Native.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+
+<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<part id="Main documentation">
+ <title>Main Documentation</title>
+ <partintro>
+ <para>
+ Below you find the essential documentation on the current JBossWS-Native release. That covers a quick start, a full user guide and tooling. You can read more on
+ JBoss Web Service Framework on the JBossWS Wiki at <ulink url="http://community.jboss.org/wiki/JBossWS">http://community.jboss.org/wiki/JBossWS</ulink>.
+ </para>
+ <para>
+ Please note, the wiki also offers a <ulink url="http://www.jboss.org/community/docs/DOC-13531">Guided Tour</ulink> along the JBossWS documentation, for those who
+ don't know where to start from when dealing with webservices in general.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-QuickStart.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-UserGuide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- remove WSF stuff from generated page -->
+ <xi:include href="JBossWS-NativeUserGuide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSTools.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsconsume.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsprovide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsrunclient.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Additional documentation">
+ <title>Additional documentation</title>
+ <partintro>
+ <para>
+ This section of the book provides documentation on common additional user requirements, like enabling authentication, securing the transport, etc.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-Authentication.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Securetransport.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-WS-Securityoptions.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Endpointmanagement.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Recordsmanagement.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSEndpointConfiguration.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSClientConfiguration.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Samples, Tutorials, references">
+ <title>Samples & Tutorials</title>
+ <partintro>
+ <para>
+ Below you find few tutorials on WS-* technologies usage as well as a brief list of reference links and the list of supported JAX-WS annotations.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-NativeWS-AddressingTutorial.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-NativeWS-ReliableMessagingTutorial.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Advancedsamples.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Asynchronousinvocationssample.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Securityandattachmentssample.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Articlesandspecs.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSAnnotations.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+</book>
Added: stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-NativeUserGuide.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,884 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-NativeUserGuide"><title>JBossWS-NativeUserGuide</title><para>This page covers features available in <emphasis role="bold">JBossWS Native stack only</emphasis>. <link linkend="chap_JBossWS-UserGuide">Please refer to the common user guide</link> for a basic introduction to JAX-WS programming as well as documentation on all features, tools, etc. the JBossWS Web Service Framework provides for every supported stack (including Native stack).</para> <para> </para><section id="JBossWS-NativeUserGuide_Secure_endpoints"><title>Secure endpoints</title><para>Securing an endpoint requires you to <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Authentication">set the authentication configuration</ulink>.</para><para>Then you might want to secure the communication between service provider and consumer. This can be done at different levels:</para><itemizedlist><listitem><para> <ulink url="http://jbossws.jboss.o!
rg/mediawiki/index.php?title=Secure_transport">Secure the HTTP transport</ulink> </para></listitem><listitem><para> WS-Security</para></listitem></itemizedlist></section>
+<section id="JBossWS-NativeUserGuide_JBossWS_Native_WS_extensions"><title>JBossWS Native WS-* extensions</title><section id="JBossWS-NativeUserGuide_WSAddressing"><title>WS-Addressing</title><para>This section describes how <ulink url="http://www.w3.org/TR/ws-addr-core">WS-Addressing</ulink> can be used to provide a stateful service endpoint.</para><section id="JBossWS-NativeUserGuide_Specifications"><title>Specifications</title><para>WS-Addressing is defined by a combination of the following specifications from the W3C Candidate Recommendation 17 August 2005. The WS-Addressing API is standardized by <ulink url="http://www.jcp.org/en/jsr/detail?id=261">JSR-261 - Java API for XML Web Services Addressing</ulink></para><itemizedlist><listitem><para> <ulink url="http://www.w3.org/TR/ws-addr-core">Web Services Addressing 1.0 - Core</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/ws-addr-soap">Web Services Addressing 1.0 - SOAP Binding</ulink></para></!
listitem></itemizedlist></section>
+<section id="JBossWS-NativeUserGuide_Addressing_Endpoint"><title>Addressing Endpoint</title><para>The following endpoint implementation has a set of operation for a typical stateful shopping chart application.</para><screen xml:space="preserve"> @WebService(name = "StatefulEndpoint", targetNamespace = "<ulink url="http://org.jboss.ws/samples/wsaddressing">http://org.jboss.ws/samples/wsaddressing</ulink>", serviceName = "TestService")
+ @EndpointConfig(configName = "Standard WSAddressing Endpoint")
+ @HandlerChain(file = "WEB-INF/jaxws-handlers.xml")
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> StatefulEndpointImpl <emphasis role="bold">implements</emphasis> StatefulEndpoint, ServiceLifecycle
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> addItem(String item)
+ { ... }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> checkout()
+ { ... }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String getItems()
+ { ... }
+ }
+</screen><para>It uses the <link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">Standard WSAddressing Endpoint</link> to enable the server side addressing handler. It processes the incomming WS-Addressing header elements and provides access to them through the JSR-261 API.</para><para>The endpoint handler chain</para><screen xml:space="preserve"><handler-chains xmlns="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>" xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink> javaee_web_services_1_2.xsd">
+
+ <handler-chain>
+ <protocol-bindings>##SOAP11_HTTP</protocol-bindings>
+ <handler>
+ <handler-name>Application Server Handler</handler-name>
+ <handler-class>org.jboss.test.ws.jaxws.samples.wsaddressing.ServerHandler</handler-class>
+ </handler>
+ </handler-chain></handler-chains>
+</screen><para>defines an application specific hander that assignes/processes stateful client ids.</para></section>
+<section id="JBossWS-NativeUserGuide_Addressing_Client"><title>Addressing Client</title><para>On the client side there are similar handlers that does the reverse. It uses the JSR-261 API to add WS-Addressing header elements including the clientid association.</para><para> The client sets a custom handler chain in the binding</para><screen xml:space="preserve"> Service service = Service.create(wsdlURL, serviceName);
+ port1 = (StatefulEndpoint)service.getPort(StatefulEndpoint.class);
+ BindingProvider bindingProvider = (BindingProvider)port1;
+
+ List<Handler> customHandlerChain = <emphasis role="bold">new</emphasis> ArrayList<Handler>();
+ customHandlerChain.add(<emphasis role="bold">new</emphasis> ClientHandler());
+ customHandlerChain.add(<emphasis role="bold">new</emphasis> WSAddressingClientHandler());
+ bindingProvider.getBinding().setHandlerChain(customHandlerChain);
+</screen><para>The WSAddressingClientHandler is provided by JBossWS and reads/writes the addressing properties and puts then into the message context.</para><para><emphasis role="bold">A client connecting to the stateful endpoint</emphasis></para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> AddressingStatefulTestCase <emphasis role="bold">extends</emphasis> JBossWSTest
+ {
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> testAddItem() <emphasis role="bold">throws</emphasis> Exception
+ {
+ port1.addItem("Ice Cream");
+ port1.addItem("Ferrari");
+
+ port2.addItem("Mars Bar");
+ port2.addItem("Porsche");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> testGetItems() <emphasis role="bold">throws</emphasis> Exception
+ {
+ String items1 = port1.getItems();
+ assertEquals("[Ice Cream, Ferrari]", items1);
+
+ String items2 = port2.getItems();
+ assertEquals("[Mars Bar, Porsche]", items2);
+ }
+ }
+</screen><para><emphasis role="bold">SOAP message exchange</emphasis></para><para>Below you see the SOAP messages that are being exchanged.</para><screen xml:space="preserve"><env:Envelope xmlns:env='<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>'><env:Header xmlns:wsa='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http://schemas.xmlsoap.org/ws/2004/08/addressing</ulink>'>
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='<ulink url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+ </wsa:ReferenceParameters></env:Header><env:Body>
+ <ns1:addItem xmlns:ns1='<ulink url="http://org.jboss.ws/samples/wsaddr">http://org.jboss.ws/samples/wsaddr</ulink>'>
+ <String_1>Ice Cream</String_1>
+ </ns1:addItem></env:Body>
+</env:Envelope>
+
+<env:Envelope xmlns:env='<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>'><env:Header xmlns:wsa='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http://schemas.xmlsoap.org/ws/2004/08/addressing</ulink>'>
+ <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='<ulink url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid></env:Header><env:Body>
+ <ns1:addItemResponse xmlns:ns1='<ulink url="http://org.jboss.ws/samples/wsaddr'/">http://org.jboss.ws/samples/wsaddr'/</ulink>></env:Body>
+</env:Envelope>
+
+ ...
+
+<env:Envelope xmlns:env='<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>'>
+ <env:Header xmlns:wsa='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http://schemas.xmlsoap.org/ws/2004/08/addressing</ulink>'>
+ <wsa:To>uri:jbossws-samples-wsaddr/TestService</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/action</wsa:Action>
+ <wsa:ReferenceParameters>
+ <ns1:clientid xmlns:ns1='<ulink url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+ </wsa:ReferenceParameters>
+ </env:Header>
+ <env:Body>
+ <ns1:getItems xmlns:ns1='<ulink url="http://org.jboss.ws/samples/wsaddr'/">http://org.jboss.ws/samples/wsaddr'/</ulink>>
+ </env:Body>
+</env:Envelope>
+
+<env:Envelope xmlns:env='<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>'>
+ <env:Header xmlns:wsa='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/addressing">http://schemas.xmlsoap.org/ws/2004/08/addressing</ulink>'>
+ <wsa:To>http://www.w3.org/2005/08/addressing/anonymous</wsa:To>
+ <wsa:Action>http://org.jboss.ws/addressing/stateful/actionReply</wsa:Action>
+ <ns1:clientid xmlns:ns1='<ulink url="http://somens">http://somens</ulink>'>clientid-1</ns1:clientid>
+ </env:Header>
+ <env:Body>
+ <ns1:getItemsResponse xmlns:ns1='<ulink url="http://org.jboss.ws/samples/wsaddr">http://org.jboss.ws/samples/wsaddr</ulink>'>
+ <result>[Ice Cream, Ferrari]</result>
+ </ns1:getItemsResponse>
+ </env:Body>
+</env:Envelope></screen></section>
+<section id="JBossWS-NativeUserGuide_Tutorial"><title>Tutorial</title><para>For further details please take a look at our <link linkend="chap_JBossWS-NativeWS-AddressingTutorial">WS-Addressing Tutorial</link>.</para><para> </para></section>
+</section>
+<section id="JBossWS-NativeUserGuide_WSBPEL"><title>WS-BPEL</title><para>WS-BPEL is not supported with JAX-WS, please refer to <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=JAX-RPC_User_Guide#WS-...">JAX-RPC User Guide#WS-BPEL</ulink>.</para><para> </para></section>
+<section id="JBossWS-NativeUserGuide_WSEventing"><title>WS-Eventing</title><para>WS-Eventing specifies a set of operations that allow an event consumer to register (subscribe) with an event producer (source) to receive events (notifications) in an asynchronous fashion.</para><section id="JBossWS-NativeUserGuide_Specifications_431795"><title>Specifications</title><para>WS-Eventing is defined by the combination of the following specifications:</para><itemizedlist><listitem><para> <ulink url="ftp://www6.software.ibm.com/software/developer/library/ws-eventing/WS-Eve...">WS-Eventing specification</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/ws-addr-core">WS-Addressing Specifications</ulink> </para></listitem></itemizedlist><para>The following section will introduce the main eventing actors and their responsiblities.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>The original eventing specification builds upon WS-Add!
ressing 2004/08. JBossWS however decided to stick to the latest version, which is the W3C candidate release.</para><para> </para></para></note></section>
+<section id="JBossWS-NativeUserGuide_Collaboration"><title>Collaboration</title><ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Image:EventingCollabor..."/>Eventing collaboration<orderedlist><listitem><para> An event sink (web service client) sends a subscription request to the event source endpoint. This includes the event sink endpoint address where notifications should delivered. Upon successful subscription the sink receives a leased subscription ID that can be used to identify the client in subsequent requests. </para></listitem><listitem><para> A successfully registered event sink directs management requests (Renew, GetStatus, Unsubscribe) to the subscription manager endpoint using the previously received subscription ID. The subscription manager endpoint address was returned as part of the subscription response in the first place. </para></listitem><listitem><para> The actual event source (application) emits notification messages through the JBos!
sWS-Eventing module. JBossWS-Eventing dispatches the notification to any subscriber endpoint that is registered with a particular event source.s </para></listitem><listitem><para> Besides notifications JBossWS-Eventing may emit lifecycle events at any time, i.e. to inform an event sink that a subscription was canceled. This can be the case when the subscription expired or the event source was undeployed. </para></listitem></orderedlist><para>It is the users responsibility to supply the web service endpoints (EventSourceEndpoint, SubscriptionManagerEndpoint) that are required for a complete event source deployment. Fortunatly JBossWS-Eventing already ships with a implementation that can be used right away. All that's left todo is packaging of standard JSR-109 deployment archive that includes the event source specific WSDL and points to the JBossWS-Eventing endpoint implementations.</para><para>The relevant steps are:</para><itemizedlist><listitem><para> Create a custom WSDL !
that describes your event source, in respect to the notificati!
on schem
a (1) and the fact that is actually contains an event source port (2) </para></listitem><listitem><para> Use the JBossWS SEI (3) and endpoint (4) implementations (web.xml).</para></listitem></itemizedlist><para> </para></section>
+<section id="JBossWS-NativeUserGuide_Setup_an_event_source_endpoint"><title>Setup an event source endpoint</title><para>With JAX-WS the event source setup has actually become quite easy. All you need to do is to subclass your endpoint implementation from <computeroutput>AbstractEventSourceEndpoint</computeroutput> and a subscription manager from <computeroutput>AbstractSubscriptionManagerEndpoint</computeroutput> and finally point that implementation to a <ulink url="http://community.jboss.org/docs/DOC-13541">event source specific WSDL</ulink>.</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wseventing;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+<emphasis role="bold">import</emphasis> org.jboss.logging.Logger;
+<emphasis role="bold">import</emphasis> org.jboss.ws.annotation.EndpointConfig;
+<emphasis role="bold">import</emphasis> org.jboss.ws.extensions.eventing.jaxws.AbstractEventSourceEndpoint;
+
+/**
+ * @author <ulink url="mailto:Heiko.Braun@jboss.org">Heiko.Braun(a)jboss.org</ulink>
+ * @version $Id$
+ * @since 18.01.2007
+ */
+@WebService( (1)
+ name = "EventSource",
+ portName = "EventSourcePort",
+ targetNamespace = "<ulink url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://schemas.xmlsoap.org/ws/2004/08/eventing</ulink>",
+ wsdlLocation = "/WEB-INF/wsdl/sysmon.wsdl", (2)
+ endpointInterface = "org.jboss.ws.extensions.eventing.jaxws.EventSourceEndpoint")
+@EndpointConfig(configName = "Standard WSAddressing Endpoint") (3)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SysmonRegistrationEndpoint <emphasis role="bold">extends</emphasis> AbstractEventSourceEndpoint { (4)
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> Logger log = Logger.getLogger(SysmonRegistrationEndpoint.class);
+
+ <emphasis role="bold">protected</emphasis> Logger getLogger()
+ {
+ <emphasis role="bold">return</emphasis> log;
+ }
+}</screen><orderedlist><listitem><para> Of course we need a <computeroutput>@WebService</computeroutput> annotation </para></listitem><listitem><para> It's important to override the WSDL here </para></listitem><listitem><para> You need to tell JBossWS that it requires WS-Addressing for this endpoint </para></listitem><listitem><para> Subclass a predefined implementation that knows how to delegate to the actual eventing service implementation</para></listitem></orderedlist></section>
+<section id="JBossWS-NativeUserGuide_The_WSDL_that_describes_an_event_source"><title>The WSDL that describes an event source</title><para>Even though we are already using the annotation driven approach, JBossWS eventing still requires an event source specific WSDL.</para><para>The following excerpt shows the relevant WSDL details that describe an event source.</para><screen xml:space="preserve"> <?xml version="1.0" encoding="UTF-8"?>
+
+ <wsdl:definitions
+ targetNamespace="<ulink url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmon</ulink>"
+ xmlns:tns="<ulink url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmon</ulink>"
+ xmlns:wse='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://schemas.xmlsoap.org/ws/2004/08/eventing</ulink>'
+ xmlns:wsdl='<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>'
+ xmlns:wsa10='<ulink url="http://www.w3.org/2005/08/addressing">http://www.w3.org/2005/08/addressing</ulink>'
+ xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'
+ xmlns:soap="<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>">
+
+ <wsdl:import
+(1) namespace='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://schemas.xmlsoap.org/ws/2004/08/eventing</ulink>'
+ location='jbwse.wsdl' />
+
+ <wsdl:types>
+
+ <xs:schema targetNamespace='<ulink url="http://schemas.xmlsoap.org/ws/2004/08/eventing">http://schemas.xmlsoap.org/ws/2004/08/eventing</ulink>'>
+(2) <xs:include schemaLocation='jbwse.xsd'/>
+ </xs:schema>
+
+(3) <xs:schema
+ targetNamespace="<ulink url="http://www.jboss.org/sysmon">http://www.jboss.org/sysmon</ulink>"
+ elementFormDefault="qualified"
+ blockDefault="#all">
+ <xs:element name="SystemStatus">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="Time " type="xs:dateTime"/>
+ <xs:element name="HostName" type="xs:string"/>
+ <xs:element name="HostAddress" type="xs:string"/>
+ <xs:element name="ActiveThreadCount" type="xs:int"/>
+ <xs:element name="FreeMemory" type="xs:string"/>
+ <xs:element name="MaxMemory" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:schema>
+
+ </wsdl:types>
+
+ <wsdl:message name='SystemInfoMsg'>
+ <wsdl:part name='body' element='tns:SystemStatus'/>
+ </wsdl:message>
+
+(4) <wsdl:portType name='SystemInfo' wse:EventSource='true'>
+ <wsdl:operation name='SysmonOp'>
+ <wsdl:output message='tns:SystemInfoMsg'/>
+ </wsdl:operation>
+ </wsdl:portType>
+
+ <wsdl:binding name="SystemInfoBinding" type="tns:SystemInfo">
+ <soap:binding style="document" transport="<ulink url="http://schemas.xmlsoap.org/soap/http">http://schemas.xmlsoap.org/soap/http</ulink>"/>
+ <wsdl:operation name="SysmonOp">
+ <soap:operation soapAction=""/>
+ <wsdl:output>
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding></wsdl:definitions>
+</screen><orderedlist><listitem><para> Import the default eventing WSDL, that includes service and port declarations. </para></listitem><listitem><para> Include the default eventing Types </para></listitem><listitem><para> Specifiy the notitification message schema. </para></listitem><listitem><para> Declare a port type, attributed "wse:EventSource='true'" that points to your notification message schema.</para></listitem></orderedlist></section>
+<section id="JBossWS-NativeUserGuide_Emitting_notifications"><title>Emitting notifications</title><para>JBossWS-Eventing registeres a event dispatcher within local JNDI tree that can be used to emit notifications from applications.</para><screen xml:space="preserve"> java:/EventDispatcher
+</screen><para>The event dispatcher interface:</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> EventDispatcher
+ {
+ <emphasis role="bold">void</emphasis> dispatch(URI eventSourceNS, Element payload);
+ }
+</screen><para><emphasis role="bold"> Example notification </emphasis></para><screen xml:space="preserve">(1) URI eventSourceURI = <emphasis role="bold">new</emphasis> URI("<ulink url="http://http://www.jboss.org/sysmon/SystemInfo">http://http://www.jboss.org/sysmon/SystemInfo</ulink>");
+(2) Element payload = DOMUtils.parse("SOME XML STRING");
+ <emphasis role="bold">try</emphasis>
+ {
+ InitialContext iniCtx = getInitialContext();
+(3) EventDispatcher delegate = (EventDispatcher)
+ iniCtx.lookup(EventingConstants.DISPATCHER_JNDI_NAME);
+(4) delegate.dispatch(eventSourceURI, payload);
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ //
+ }</screen><orderedlist><listitem><para> Address your event source correctly (TargetNamespace+PortTypeName) </para></listitem><listitem><para> Create your payload </para></listitem><listitem><para> Lookup dispatcher from JNDI </para></listitem><listitem><para> Dispatch notification. </para></listitem></orderedlist><para> </para><para>The SubscriptionManager MBean is the actual core component that drives the JBossWS-Eventing implementation. It can be accessed through the jmx-console.</para><screen xml:space="preserve"> jboss.ws.eventing:service=SubscriptionManager
+</screen><para>Management operations exist to monitor and maintain active subscritions and deployed event sources. The current implementation is backed by a ThreadPoolExecutor, that asynchronously delivers messages to event sink endpoints. It can be configured through the following attributes:</para><itemizedlist><listitem><para> corePoolSize - average number of idle threads </para></listitem><listitem><para> maximumPoolSize - maximum number of threads </para></listitem><listitem><para> eventKeepAlive - keep alive before an undelivered event message is discarded.</para></listitem></itemizedlist><para> </para><para> </para></section>
+</section>
+<section id="JBossWS-NativeUserGuide_WSSecurity"><title>WS-Security</title><para>WS-Security addresses message level security. It standardizes authorization, encryption, and digital signature processing of web services. Unlike transport security models, such as SSL, WS-Security applies security directly to the elements of the web service message. This increases the flexibility of your web services, by allowing any message model to be used (point to point, multi-hop relay, etc).</para><para>This chapter describes how to use WS-Security to sign and encrypt a simple SOAP message.</para><para><emphasis role="bold">Specifications</emphasis></para><para>WS-Security is defined by the combination of the following specifications:</para><itemizedlist><listitem><para> <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-secu...">SOAP Message Security 1.0</ulink> </para></listitem><listitem><para> <ulink url="http://docs.oasis-open.org/wss/2004/01/o!
asis-200401-wss-username-token-profile-1.0.pdf">Username Token Profile 1.0</ulink> </para></listitem><listitem><para> <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...">X.509 Token Profile 1.0</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlenc-core">W3C XML Encryption</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmldsig-core">W3C XML Signature</ulink> </para></listitem><listitem><para> <ulink url="http://www.ws-i.org/Profiles/BasicSecurityProfile-1.0.html">Basic Security Profile 1.0 (Still in Draft)</ulink></para></listitem></itemizedlist><section id="JBossWS-NativeUserGuide_Endpoint_configuration"><title>Endpoint configuration</title><para>JBossWS uses handlers to identify ws-security encoded requests and invoke the security components to sign and encrypt messages. In order to enable security processing, the client and server side need to include a corresponding hand!
ler configuration. The preferred way is to reference a predefi!
ned <lin
k linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</link> or <link linkend="chap_JBossWS-JAX-WSClientConfiguration">JAX-WS_Client_Configuration</link> respectively.</para><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>You need to setup both the endpoint configuration and the WSSE declarations. That's two separate steps.</emphasis></para></para></note></section>
+<section id="JBossWS-NativeUserGuide_Server_side_WSSE_declaration_jbosswsseserverxml"><title>Server side WSSE declaration (jboss-wsse-server.xml)</title><para>In this example we configure both the client and the server to sign the message body. Both also require this from each other. So, if you remove either the client or the server security deployment descriptor, you will notice that the other party will throw a fault explaining that the message did not conform to the proper security requirements.</para><screen xml:space="preserve"> <jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ (1) <key-store-file>WEB-INF/wsse.keystore</key-store-file>
+ (2) <key-store-password>jbossws</key-store-password>
+ (3) <trust-store-file>WEB-INF/wsse.truststore</trust-store-file>
+ (4) <trust-store-password>jbossws</trust-store-password>
+ (5) <config>
+ (6) <sign type="x509v3" alias="wsse"/>
+ (7) <requires>
+ (8) <signature/>
+ </requires>
+ </config>
+ </jboss-ws-security>
+</screen><para> </para><orderedlist><listitem><para> This specifies that the key store we wish to use is WEB-INF/wsse.keystore, which is located in our war file. </para></listitem><listitem><para> This specifies that the store password is "jbossws". Password can be encypted using the {EXT} and {CLASS} commands. Please see samples for their usage. </para></listitem><listitem><para> This specifies that the trust store we wish to use is WEB-INF/wsse.truststore, which is located in our war file. </para></listitem><listitem><para> This specifies that the trust store password is also "jbossws". Password can be encrypted using the {EXT} and {CLASS} commands. Please see samples for their usage. </para></listitem><listitem><para> Here we start our root config block. The root config block is the default configuration for all services in this war file. </para></listitem><listitem><para> This means that the server must sign the message body of all responses. Type means that we are to !
use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/key pair to use for signing is in the key store under the "wsse" alias </para></listitem><listitem><para> Here we start our optional requires block. This block specifies all security requirements that must be met when the server receives a message. </para></listitem><listitem><para> This means that all web services in this war file require the message body to be signed. </para></listitem></orderedlist><para>By default an endpoint does not use the WS-Security configuration. Use the proprietary @EndpointConfig annotation to set the config name. See <link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JAX-WS_Endpoint_Configuration</link> for the list of available config names.</para><screen xml:space="preserve">@WebService
+@EndpointConfig(configName = "Standard WSSecurity Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> HelloJavaBean
+{
+ ...
+}
+</screen></section>
+<section id="JBossWS-NativeUserGuide_Client_side_WSSE_declaration_jbosswsseclientxml"><title>Client side WSSE declaration (jboss-wsse-client.xml)</title><screen xml:space="preserve"> <jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ (1) <config>
+ (2) <sign type="x509v3" alias="wsse"/>
+ (3) <requires>
+ (4) <signature/>
+ </requires>
+ </config>
+ </jboss-ws-security>
+</screen><para> </para><orderedlist><listitem><para> Here we start our root config block. The root config block is the default configuration for all web service clients (Call, Proxy objects). </para></listitem><listitem><para> This means that the client must sign the message body of all requests it sends. Type means that we are to use a X.509v3 certificate (a standard certificate). The alias option says that the certificate/key pair to use for signing is in the key store under the "wsse" alias </para></listitem><listitem><para> Here we start our optional requires block. This block specifies all security requirements that must be met when the client receives a response. </para></listitem><listitem><para> This means that all web service clients must receive signed response messages.</para></listitem></orderedlist><para> </para><section id="JBossWS-NativeUserGuide_Client_side_key_store_configuration"><title>Client side key store configuration</title><para>We did not specify !
a key store or trust store, because client app uses the WSSE System properties instead. If this was a Web or EJB client (meaning a webservice client in a war or EJB jar file), then we would have to specify them in the client descriptor.</para><para>Here is an excerpt from the JBossWS samples:</para><screen xml:space="preserve"><sysproperty key="org.jboss.ws.wsse.keyStore"
+ value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.keystore"/>
+<sysproperty key="org.jboss.ws.wsse.trustStore"
+ value="${tests.output.dir}/resources/jaxrpc/samples/wssecurity/wsse.truststore"/>
+<sysproperty key="org.jboss.ws.wsse.keyStorePassword" value="jbossws"/>
+<sysproperty key="org.jboss.ws.wsse.trustStorePassword" value="jbossws"/>
+<sysproperty key="org.jboss.ws.wsse.keyStoreType" value="jks"/>
+<sysproperty key="org.jboss.ws.wsse.trustStoreType" value="jks"/>
+</screen><para><emphasis role="bold">SOAP message exchange</emphasis></para><para>Below you see the incomming SOAP message with the details of the security headers ommited. The idea is, that the SOAP body is still plain text, but it is signed in the security header and can therefore not manipulated in transit.</para><para>Incomming SOAPMessage</para><screen xml:space="preserve"> <env:Envelope xmlns:env="<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>">
+ <env:Header>
+ <wsse:Security env:mustUnderstand="1" ...>
+ <wsu:Timestamp wsu:Id="timestamp">...</wsu:Timestamp>
+ <wsse:BinarySecurityToken ...>
+ ...
+ </wsse:BinarySecurityToken>
+ <ds:Signature xmlns:ds="<ulink url="http://www.w3.org/2000/09/xmldsig#">http://www.w3.org/2000/09/xmldsig#</ulink>">
+ ...
+ </ds:Signature>
+ </wsse:Security>
+ </env:Header>
+ <env:Body wsu:Id="element-1-1140197309843-12388840" ...>
+ <ns1:echoUserType xmlns:ns1="<ulink url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>">
+ <UserType_1 xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>">
+ <msg>Kermit</msg>
+ </UserType_1>
+ </ns1:echoUserType>
+ </env:Body>
+ </env:Envelope></screen></section>
+</section>
+<section id="JBossWS-NativeUserGuide_Installing_the_BouncyCastle_JCE_provider_JDK_14"><title>Installing the BouncyCastle JCE provider (JDK 1.4)</title><para>The information below has originaly been provided by <ulink url="http://www.bouncycastle.org/specifications.html#install">The Legion of the Bouncy Castle</ulink>.</para><para>The provider can be configured as part of your environment via static registration by adding an entry to the java.security properties file (found in $JAVA_HOME/jre/lib/security/java.security, where $JAVA_HOME is the location of your JDK/JRE distribution). You'll find detailed instructions in the file but basically it comes down to adding a line:</para><screen xml:space="preserve"> security.provider.<n>=org.bouncycastle.jce.provider.BouncyCastleProvider
+</screen><para>Where <n> is the preference you want the provider at.</para><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>Issues may arise if the Sun providers are not first.</emphasis></para></para></note><para><emphasis>Where you put the jar is mostly up to you, although with jdk1.4 the best (and in some cases only) place to have it is in $JAVA_HOME/jre/lib/ext. Under Windows there will normally be a JRE and a JDK install of Java if you think you have installed it correctly and it still doesn't work chances are you have added the provider to the installation not being used.</emphasis></para></section>
+<section id="JBossWS-NativeUserGuide_Keystore_truststore__What"><title>Keystore, truststore - What?</title><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>If you having a hard time understanding how the different trust- and keystore configurations are used for signature and encryption, then read this thread first: <link linkend="chap_index">http://www.jboss.org/index.html?module=bb&op=viewtopic&t=94406</link></emphasis></para></para></note></section>
+<section id="JBossWS-NativeUserGuide_Advanced_configuration"><title>Advanced configuration</title><para>Further information and examples covering <link linkend="chap_JBossWS-WS-Securityoptions">advanced WS-Security configuration options</link> are available. Those might help when specific settings are required to obtain interoperability with other vendors' WS-Security implementation.</para></section>
+</section>
+<section id="JBossWS-NativeUserGuide_WSReliable_Messaging"><title>WS-Reliable Messaging</title><para>WS-Reliable Messaging specifies how a reliable web service communication can be achieved.</para><para>Please take a look at our <link linkend="chap_JBossWS-NativeWS-ReliableMessagingTutorial">WS-Reliable Messaging Tutorial</link> for configuration details.</para></section>
+<section id="JBossWS-NativeUserGuide_WSTransaction"><title>WS-Transaction</title><para>Support for the WS-Coordination, WS-AtomicTransaction and WS-BusinessActivity specifications will be provided by technology recently acquired from Arjuna Technologies Ltd. This technology will be present within the JBoss Transactions 4.2.1 release. Further information can be obtained from the <ulink url="http://labs.jboss.org/portal/jbosstm">JBoss Transactions Project</ulink></para></section>
+<section id="JBossWS-NativeUserGuide_XML_Registries"><title>XML Registries</title><para>J2EE 1.4 mandates support for Java API for XML Registries (JAXR). Inclusion of a XML Registry with the J2EE 1.4 certified Application Server is optional. Starting jboss-4.0.2, JBoss ships a UDDI v2.0 compliant registry, the Apache jUDDI registry. We also provide support for JAXR Capability Level 0 (UDDI Registries) via integration of Apache Scout.</para><para>This chapter describes how to configure the jUDDI registry in JBoss and some sample code outlines for using JAXR API to publish and query the jUDDI registry.</para><section id="JBossWS-NativeUserGuide_Apache_jUDDI_Configuration"><title>Apache jUDDI Configuration</title><para>Configuration of the jUDDI registry happens via an MBean Service that is deployed in the juddi-service.sar archive in the "all" configuration. The configuration of this service can be done in the jboss-service.xml of the META-INF directory in the juddi-service.s!
ar</para><para>Let us look at the individual configuration items that can be changed.</para><para>DataSources configuration</para><screen xml:space="preserve"> <!-- Datasource to Database-->
+ <attribute name="DataSourceUrl">java:/DefaultDS</attribute>
+</screen><para>Database Tables (Should they be created on start, Should they be dropped on stop, Should they be dropped on start etc)</para><screen xml:space="preserve"> <!-- Should all tables be created on Start-->
+ <attribute name="CreateOnStart">false</attribute>
+ <!-- Should all tables be dropped on Stop-->
+ <attribute name="DropOnStop">true</attribute>
+ <!-- Should all tables be dropped on Start-->
+ <attribute name="DropOnStart">false</attribute>
+</screen><para>JAXR Connection Factory to be bound in JNDI. (Should it be bound? and under what name?)</para><screen xml:space="preserve"> <!-- Should I bind a Context to which JaxrConnectionFactory bound-->
+ <attribute name="ShouldBindJaxr">true</attribute>
+
+ <!-- Context to which JaxrConnectionFactory to bind to. If you have remote clients, please bind it to the global namespace(default behavior).
+ To just cater to clients running on the same VM as JBoss, change to java:/JAXR -->
+ <attribute name="BindJaxr">JAXR</attribute></screen><para> </para><para>Other common configuration:</para><para>Add authorized users to access the jUDDI registry. (Add a sql insert statement in a single line)</para><screen xml:space="preserve"> Look at the script META-INF/ddl/juddi_data.ddl for more details. Example for a user 'jboss'
+
+ INSERT INTO PUBLISHER (PUBLISHER_ID,PUBLISHER_NAME,
+ EMAIL_ADDRESS,IS_ENABLED,IS_ADMIN)
+ VALUES ('jboss','JBoss User','jboss@xxx','true','true');</screen></section>
+<section id="JBossWS-NativeUserGuide_JBoss_JAXR_Configuration"><title>JBoss JAXR Configuration</title><para>In this section, we will discuss the configuration needed to run the JAXR API. The JAXR configuration relies on System properties passed to the JVM. The System properties that are needed are:</para><screen xml:space="preserve"> javax.xml.registry.ConnectionFactoryClass=org.apache.ws.scout.registry.ConnectionFactoryImpl
+ jaxr.query.url=http://localhost:8080/juddi/inquiry
+ jaxr.publish.url=http://localhost:8080/juddi/publish
+ juddi.proxy.transportClass=org.jboss.jaxr.juddi.transport.SaajTransport
+</screen><para>Please remember to change the hostname from "localhost" to the hostname of the UDDI service/JBoss Server.</para><para>You can pass the System Properties to the JVM in the following ways:</para><itemizedlist><listitem><para> When the client code is running inside JBoss (maybe a servlet or an EJB). Then you will need to pass the System properties in the run.sh/run.bat scripts to the java process via the "-D" option. </para></listitem><listitem><para> When the client code is running in an external JVM. Then you can pass the properties either as "-D" options to the java process or explicitly set them in the client code(not recommended). </para></listitem></itemizedlist><screen xml:space="preserve"> System.setProperty(propertyname, propertyvalue);</screen></section>
+<section id="JBossWS-NativeUserGuide_JAXR_Sample_Code"><title>JAXR Sample Code</title><para>There are two categories of API: JAXR Publish API and JAXR Inquiry API. The important JAXR interfaces that any JAXR client code will use are the following.</para><itemizedlist><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/RegistryService....">javax.xml.registry.RegistryService</ulink> From J2EE 1.4 JavaDoc: "This is the principal interface implemented by a JAXR provider. A registry client can get this interface from a Connection to a registry. It provides the methods that are used by the client to discover various capability specific interfaces implemented by the JAXR provider." </para></listitem><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/BusinessLifeCycl...">javax.xml.registry.BusinessLifeCycleManager</ulink> From J2EE 1.4 JavaDoc: "The BusinessLifeCycleManager interface, which is exposed b!
y the Registry Service, implements the life cycle management functionality of the Registry as part of a business level API. Note that there is no authentication information provided, because the Connection interface keeps that state and context on behalf of the client." </para></listitem><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/xml/registry/BusinessQueryMan...">javax.xml.registry.BusinessQueryManager</ulink> From J2EE 1.4 JavaDoc: "The BusinessQueryManager interface, which is exposed by the Registry Service, implements the business style query interface. It is also referred to as the focused query interface." </para></listitem></itemizedlist><para>Let us now look at some of the common programming tasks performed while using the JAXR API:</para><para>Getting a JAXR Connection to the registry.</para><screen xml:space="preserve"> String queryurl = System.getProperty("jaxr.query.url", "<ulink url="http://localhost:8080/juddi/inqui!
ry">http://localhost:8080/juddi/inquiry</ulink>");
+ String puburl = System.getProperty("jaxr.publish.url", "<ulink url="http://localhost:8080/juddi/publish">http://localhost:8080/juddi/publish</ulink>");
+
+ Properties props = <emphasis role="bold">new</emphasis> Properties();
+ props.setProperty("javax.xml.registry.queryManagerURL", queryurl);
+ props.setProperty("javax.xml.registry.lifeCycleManagerURL", puburl);
+
+ String transportClass = System.getProperty("juddi.proxy.transportClass", "org.jboss.jaxr.juddi.transport.SaajTransport");
+ System.setProperty("juddi.proxy.transportClass", transportClass);
+
+ // Create the connection, passing it the configuration properties
+ factory = ConnectionFactory.newInstance();
+ factory.setProperties(props);
+ connection = factory.createConnection();
+</screen><para>Authentication with the registry.</para><screen xml:space="preserve"> /**
+ * Does authentication with the uddi registry
+ */
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> login() <emphasis role="bold">throws</emphasis> JAXRException
+ {
+ PasswordAuthentication passwdAuth = <emphasis role="bold">new</emphasis> PasswordAuthentication(userid, passwd.toCharArray());
+ Set creds = <emphasis role="bold">new</emphasis> HashSet();
+ creds.add(passwdAuth);
+
+ connection.setCredentials(creds);
+ }
+</screen><para>Save a Business</para><screen xml:space="preserve"> /**
+ * Creates a Jaxr Organization with 1 or more services
+ */
+ <emphasis role="bold">protected</emphasis> Organization createOrganization(String orgname) <emphasis role="bold">throws</emphasis> JAXRException
+ {
+ Organization org = blm.createOrganization(getIString(orgname));
+ org.setDescription(getIString("JBoss Inc"));
+ Service service = blm.createService(getIString("JBOSS JAXR Service"));
+ service.setDescription(getIString("Services of XML Registry"));
+ //Create serviceBinding
+ ServiceBinding serviceBinding = blm.createServiceBinding();
+ serviceBinding.setDescription(blm.createInternationalString("Test Service Binding"));
+
+ //Turn validation of URI off
+ serviceBinding.setValidateURI(<emphasis role="bold">false</emphasis>);
+ serviceBinding.setAccessURI("<ulink url="http://testjboss.org">http://testjboss.org</ulink>");
+
+ // Add the serviceBinding to the service
+ service.addServiceBinding(serviceBinding);
+
+ User user = blm.createUser();
+ org.setPrimaryContact(user);
+ PersonName personName = blm.createPersonName("Anil S");
+ TelephoneNumber telephoneNumber = blm.createTelephoneNumber();
+ telephoneNumber.setNumber("111-111-7777");
+ telephoneNumber.setType(<emphasis role="bold">null</emphasis>);
+ PostalAddress address = blm.createPostalAddress("111", "My Drive", "BuckHead", "GA", "USA", "1111-111", "");
+ Collection postalAddresses = <emphasis role="bold">new</emphasis> ArrayList();
+ postalAddresses.add(address);
+ Collection emailAddresses = <emphasis role="bold">new</emphasis> ArrayList();
+ EmailAddress emailAddress = blm.createEmailAddress("<ulink url="mailto:anil@apache.org">anil(a)apache.org</ulink>");
+ emailAddresses.add(emailAddress);
+
+ Collection numbers = <emphasis role="bold">new</emphasis> ArrayList();
+ numbers.add(telephoneNumber);
+ user.setPersonName(personName);
+ user.setPostalAddresses(postalAddresses);
+ user.setEmailAddresses(emailAddresses);
+ user.setTelephoneNumbers(numbers);
+
+ ClassificationScheme cScheme = getClassificationScheme("ntis-gov:naics", "");
+ Key cKey = blm.createKey("uuid:C0B9FE13-324F-413D-5A5B-2004DB8E5CC2");
+ cScheme.setKey(cKey);
+ Classification classification = blm.createClassification(cScheme, "Computer Systems Design and Related Services", "5415");
+ org.addClassification(classification);
+ ClassificationScheme cScheme1 = getClassificationScheme("D-U-N-S", "");
+ Key cKey1 = blm.createKey("uuid:3367C81E-FF1F-4D5A-B202-3EB13AD02423");
+ cScheme1.setKey(cKey1);
+ ExternalIdentifier ei = blm.createExternalIdentifier(cScheme1, "D-U-N-S number", "08-146-6849");
+ org.addExternalIdentifier(ei);
+ org.addService(service);
+ <emphasis role="bold">return</emphasis> org;
+ }
+</screen><para>Query a Business</para><screen xml:space="preserve"> /**
+ * Locale aware Search a business in the registry
+ */
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> searchBusiness(String bizname) <emphasis role="bold">throws</emphasis> JAXRException
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ // Get registry service and business query manager
+ this.getJAXREssentials();
+
+ // Define find qualifiers and name patterns
+ Collection findQualifiers = <emphasis role="bold">new</emphasis> ArrayList();
+ findQualifiers.add(FindQualifier.SORT_BY_NAME_ASC);
+ Collection namePatterns = <emphasis role="bold">new</emphasis> ArrayList();
+ String pattern = "%" + bizname + "%";
+ LocalizedString ls = blm.createLocalizedString(Locale.getDefault(), pattern);
+ namePatterns.add(ls);
+
+ // Find based upon qualifier type and values
+ BulkResponse response = bqm.findOrganizations(findQualifiers, namePatterns, null, null, null, <emphasis role="bold">null</emphasis>);
+
+ // check how many organisation we have matched
+ Collection orgs = response.getCollection();
+ <emphasis role="bold">if</emphasis> (orgs == <emphasis role="bold">null</emphasis>)
+ {
+ log.debug(" -- Matched 0 orgs");
+
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ log.debug(" -- Matched " + orgs.size() + " organizations -- ");
+
+ // then step through them
+ <emphasis role="bold">for</emphasis> (Iterator orgIter = orgs.iterator(); orgIter.hasNext();)
+ {
+ Organization org = (Organization)orgIter.next();
+ log.debug("Org name: " + getName(org));
+ log.debug("Org description: " + getDescription(org));
+ log.debug("Org key id: " + getKey(org));
+ checkUser(org);
+ checkServices(org);
+ }
+ }
+ }
+ <emphasis role="bold">finally</emphasis>
+ {
+ connection.close();
+ }
+ }
+</screen><para>For more examples of code using the JAXR API, please refer to the resources in the Resources Section.</para><para> </para></section>
+<section id="JBossWS-NativeUserGuide_Trouble_Shooting"><title>Trouble Shooting</title><itemizedlist><listitem><para> I cannot connect to the registry from JAXR. Please check the inquiry and publish url passed to the JAXR ConnectionFactory. </para></listitem><listitem><para> I cannot connect to the jUDDI registry. Please check the jUDDI configuration and see if there are any errors in the server.log. And also remember that the jUDDI registry is available only in the "all" configuration. </para></listitem><listitem><para> I cannot authenticate to the jUDDI registry. Have you added an authorized user to the jUDDI database, as described earlier in the chapter? </para></listitem><listitem><para> I would like to view the SOAP messages in transit between the client and the UDDI Registry. Please use the tcpmon tool to view the messages in transit. <ulink url="http://tcpmon.dev.java.net/">TCPMon</ulink></para></listitem></itemizedlist></section>
+<section id="JBossWS-NativeUserGuide_Resources"><title>Resources</title><itemizedlist><listitem><para> <ulink url="http://java.sun.com/webservices/jaxr/learning/tutorial/index.html">JAXR Tutorial and Code Camps</ulink> </para></listitem><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/">J2EE 1.4 Tutorial</ulink> </para></listitem><listitem><para> <ulink url="http://www.amazon.com/exec/obidos/ASIN/0321146182">J2EE Web Services by Richard Monson-Haefel</ulink></para></listitem></itemizedlist><para> </para></section>
+</section>
+<section id="JBossWS-NativeUserGuide_WSPolicy"><title>WS-Policy</title><para>The Web Services Policy Framework (WS-Policy) provides a general purpose model and corresponding syntax to describe the policies of a Web Service.</para><para>WS-Policy defines a base set of constructs that can be used and extended by other Web services specifications to describe a broad range of service requirements and capabilities.</para><para>Current JBoss implementation can instrument a webservice with policies attached at endpoint, port or port-type scope level only. There are two different methods to attach policies: providing a wsdl decorated with policies and policy attachments as defined by specifications, or using JBoss proprietary annotations. The first way has the advantage of being standard, while the second one is much more simple to implement. Of course the wsdl generated by these annotations conforms to standard defined in specifications and can be used with any ws-policy compliant!
client.</para><para>Please note that ws-policy specifications only define policy requirements and their attachment method to wsdl through specific extensions. It is out of the scope of ws-policy specifications and thus implementation to define and use the content of assertions. The way these assertions (called domain assertions or domain policies) have to be deployed and used is left to other specification like WS-Security-Policy or more generally to domain specific implementation.</para><section id="JBossWS-NativeUserGuide_Specification"><title>Specification</title><para>WS-Policy is defined by the combination of the following specifications:</para><screen xml:space="preserve"> * <ulink url="http://www.w3.org/Submission/WS-Policy/">WS-Policy specification</ulink> * <ulink url="http://www.w3.org/Submission/WS-PolicyAttachment/">WS-Policy-Attachment specification</ulink></screen></section>
+<section id="JBossWS-NativeUserGuide_WSPolicy_Example"><title>WS-Policy Example</title><para>Please take a look to our <link linkend="chap_JBossWS-NativeWS-ReliableMessagingTutorial">WS-Reliable Messaging Tutorial</link> to see how to combine WS-Policy specification with other technologies.</para></section>
+<section id="JBossWS-NativeUserGuide_Using_policies_in_a_user_provided_wsdl"><title>Using policies in a user provided wsdl</title><para>To attach policies in this manner, the only thing you have to do in a webservice class is to provide a custom wsdl. This will cause JBossws to skip wsdl generation at deploy time, since the wsdl file you provided will be published. Please refer to specification (WS-Policy-Attachment) to learn how to modify wsdl to attach a policy.</para><para>Here you find an example of a webservice class and provided wsdl with a policy containing a domain assertion for JBoss wssecurity.</para><screen xml:space="preserve">@WebService(name = "Hello",
+targetNamespace = "<ulink url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>",
+wsdlLocation="WEB-INF/wsdl/HelloService.wsdl")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<definitions name='HelloService' targetNamespace='<ulink url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>' xmlns='<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>' xmlns:ns1='<ulink url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>' xmlns:soap='<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>' xmlns:tns='<ulink url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>' xmlns:wsp='<ulink url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://schemas.xmlsoap.org/ws/2004/09/policy</ulink>' xmlns:xsd='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'><types>
+ <xs:schema targetNamespace='<ulink url="http://org.jboss.ws/samples/wssecurity">http://org.jboss.ws/samples/wssecurity</ulink>' version='1.0' xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+ <xs:complexType name='UserType'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='msg' type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema></types><wsp:Policy wsu:Id='X509EndpointPolicy' xmlns:wsu='<ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...</ulink>'>
+ <wsp:All>
+ <sp:jboss-ws-security xmlns:sp='<ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>'>
+ <sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file>
+ <sp:key-store-password>jbossws</sp:key-store-password>
+ <sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file>
+ <sp:trust-store-password>jbossws</sp:trust-store-password>
+ <sp:config>
+ <sp:encrypt alias='wsse' type='x509v3'/>
+ <sp:requires>
+ <sp:encryption/>
+ </sp:requires>
+ </sp:config>
+ </sp:jboss-ws-security>
+ </wsp:All></wsp:Policy><message name='Hello_echoUserType'>
+ <part name='user' type='ns1:UserType'/></message><message name='Hello_echoUserTypeResponse'>
+ <part name='return' type='ns1:UserType'/></message><portType name='Hello'>
+ <operation name='echoUserType' parameterOrder='user'>
+ <input message='tns:Hello_echoUserType'/>
+ <output message='tns:Hello_echoUserTypeResponse'/>
+ </operation></portType><binding name='HelloBinding' type='tns:Hello'>
+ <wsp:PolicyReference URI='#X509EndpointPolicy'/>
+ <soap:binding style='rpc' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='echoUserType'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>' use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/wssecuritypolicy">http://org.jboss.ws/samples/wssecuritypolicy</ulink>' use='literal'/>
+ </output>
+ </operation></binding><service name='HelloService'>
+ <port binding='tns:HelloBinding' name='HelloPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</definitions>
+</screen><para>Please note in the wsdl file the wsp:Policy element and the wsp:PolicyReference in 'HelloBinding' binding Element.</para><para> </para></section>
+<section id="JBossWS-NativeUserGuide_Using_policies_with_JBoss_annotations"><title>Using policies with JBoss annotations</title><para>Using JBoss proprietary annotation you only have to provide the policy xml, leaving wsdl generation to the JBossWS deployer.</para><para>There are two annotations to use, the first one (@PolicyAttachment) containing an array of the second one (@Policy): this lets you have many policies attached to a class or method. In future domain policy implementations might ship domain annotations extending the @Policy annotation to provide needed metadata directly as annotation parameters. The current @Policy annotation takes a reference to a xml file containing a generic policy description written respecting ws-policy specification rules.</para><para> </para><screen xml:space="preserve">@Target(ElementType.TYPE)
+(a)Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> PolicyAttachment {
+ Policy[] value();
+}</screen><screen xml:space="preserve">@Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> Policy {
+
+ <emphasis role="bold">public</emphasis> String policyFileLocation();
+
+ <emphasis role="bold">public</emphasis> PolicyScopeLevel scope();
+}
+</screen><para>And here you have the previous section example re-implemented using annotations and xml policy file:</para><screen xml:space="preserve">@WebService(name = "Hello", targetNamespace = "<ulink url="http://org.jboss.ws/samples/wssecurityAnnotatedpolicy">http://org.jboss.ws/samples/wssecurityAnnotatedpolicy</ulink>")
+@PolicyAttachment({@Policy( policyFileLocation="WEB-INF/Policy.xml", scope = PolicyScopeLevel.WSDL_PORT ) })
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> HelloJavaBean
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(HelloJavaBean.class);
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> UserType echoUserType(@WebParam(name = "user") UserType in0)
+ {
+ log.info(in0);
+ <emphasis role="bold">return</emphasis> in0;
+ }
+}
+</screen><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><wsp:Policy wsu:Id="X509EndpointPolicy" xmlns:wsp="<ulink url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://schemas.xmlsoap.org/ws/2004/09/policy</ulink>"
+ xmlns:wsu="<ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...</ulink>">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:jboss-ws-security xmlns:sp="<ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <sp:key-store-file>WEB-INF/wsse.keystore</sp:key-store-file>
+ <sp:key-store-password>jbossws</sp:key-store-password>
+ <sp:trust-store-file>WEB-INF/wsse.truststore</sp:trust-store-file>
+ <sp:trust-store-password>jbossws</sp:trust-store-password>
+ <sp:config>
+ <sp:encrypt type="x509v3" alias="wsse"/>
+ <sp:requires>
+ <sp:encryption/>
+ </sp:requires>
+ </sp:config>
+ </sp:jboss-ws-security>
+ </wsp:All>
+ </wsp:ExactlyOne>
+ </wsp:Policy></screen><para> </para><para> </para><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-NativeUserGuide_JMS_Transport_Clients"><title>JMS Transport Clients</title><para>Since jbossws-2.0.3 we support JAX-WS clients that use JMS transport.</para><para>JMS transport is activated on the client side when the endpoint location uses the 'jms' URL schema</para><screen xml:space="preserve"> <binding name='JMSBinding' type='tns:OrganizationJMSEndpoint'>
+ <soap:binding style='rpc' transport='<ulink url="http://www.example.org/2006/06/soap/bindings/JMS/'/">http://www.example.org/2006/06/soap/bindings/JMS/'/</ulink>>
+ <operation name='getContactInfo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>' use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>' use='literal'/>
+ </output>
+ </operation>
+ </binding>
+
+ <service name='OrganizationJMSEndpointService'>
+ <port binding='tns:JMSBinding' name='JMSEndpointPort'>
+ <soap:address location='jms://queue/RequestQueue?replyToName=queue/ResponseQueue'/>
+ </port>
+ </service>
+</screen><para>The service that implements the JMS remote connection is loaded using the key</para><screen xml:space="preserve"> org.jboss.ws.core.client.RemoteConnection.jms
+</screen><para>Like any other service, this can be overwritten using a system property.</para><para>The JAX-WS client code is essentially no different from a client using HTTP as transport</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> testJMSEndpointPort() <emphasis role="bold">throws</emphasis> Exception
+ {
+ URL wsdlURL = <emphasis role="bold">new</emphasis> File("resources/jaxws/samples/jmstransport/jmsservice.wsdl").toURL();
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/jmstransport", "OrganizationJMSEndpointService");
+ QName portName = <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/jmstransport", "JMSEndpointPort");
+
+ Service service = Service.create(wsdlURL, serviceName);
+ Organization port = service.getPort(portName, Organization.class);
+
+ String res = port.getContactInfo("mafia");
+ assertEquals("The 'mafia' boss is currently out of office, please call again.", res);
+ }
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-NativeUserGuide_DataBinding"><title>DataBinding</title><section id="JBossWS-NativeUserGuide_Using_JAXB_with_non_annotated_classes"><title>Using JAXB with non annotated classes</title><para>JAXB is heavily driven by Java Annotations on the Java Bindings. It currently doesn't support an external binding configuration. This recently became an issue for us on JBossESB since the JBossWS 2.0.0 native SOAP stack uses JAXB to perform the SOAP to Java bindings (see 1, 2). It's an issue for JBossESB simply because it needs to be able to support user definition of JBossWS native Webservice Endpoints (e.g. JSR 181) using Java typesets that have not been "JAXB Annotated" (see JAXB Introductions On JBossWS).</para><para>In order to support this, we built on a JAXB RI feature whereby it allows you to specify a RuntimeInlineAnnotationReader implementation during JAXBContext creation (see JAXBRIContext).</para><para>We call this feature "JAXB Annotation Introduction" an!
d we've made it available for general consumption i.e. it can be checked out, built and used from SVN:</para><itemizedlist><listitem><para> <ulink url="http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/">http://anonsvn.jboss.org/repos/jbossws/projects/jaxbintros/</ulink> </para></listitem></itemizedlist><para>Complete documentation can be found here:</para><itemizedlist><listitem><para> <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JAXBIntroductions">http://wiki.jboss.org/wiki/Wiki.jsp?page=JAXBIntroductions</ulink></para></listitem></itemizedlist></section>
+<section id="JBossWS-NativeUserGuide__Mapping_of_xsdany"><title> Mapping of xsd:any</title><itemizedlist><listitem><para> <ulink url="https://jaxb.dev.java.net/guide/Mapping_of__xs_any___.html">https://jaxb.dev.java.net/guide/Mapping_of__xs_any___.html</ulink></para></listitem></itemizedlist><para> </para></section>
+</section>
+<section id="JBossWS-NativeUserGuide_Attachments"><title>Attachments</title><section id="JBossWS-NativeUserGuide_MTOMXOP"><title>MTOM/XOP</title><para>This chapter describes Message Transmission Optimization Mechanism (MTOM) and XML-binary Optimized Packaging (XOP), a means of more efficiently serializing XML Infosets that have certain types of content. The related specifications are</para><itemizedlist><listitem><para><ulink url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink> </para></listitem><listitem><para><ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink></para></listitem></itemizedlist><para> </para><section id="JBossWS-NativeUserGuide_Supported_MTOM_parameter_types"><title>Supported MTOM parameter types</title><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry>image/jpeg</entry><entry>java.awt.Image</entry></r!
ow></thead><tbody><row><entry>text/xml</entry><entry>javax.xml.transform.Source</entry></row><row><entry>application/xml</entry><entry>javax.xml.transform.Source</entry></row><row><entry>application/octet-stream</entry><entry>javax.activation.DataHandler</entry></row></tbody></tgroup></informaltable><para>The above table shows a list of supported endpoint parameter types. The recommended approach is to use the <ulink url="http://java.sun.com/j2ee/1.4/docs/api/javax/activation/DataHandler.html">javax.activation.DataHandler</ulink> classes to represent binary data as service endpoint parameters.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>Microsoft endpoints tend to send any data as application/octet-stream. The only Java type that can easily cope with this ambiguity is javax.activation.DataHandler</para></para></note></section>
+<section id="JBossWS-NativeUserGuide_Enabling_MTOM_per_endpoint"><title>Enabling MTOM per endpoint</title><para>On the server side MTOM processing is enabled through the <computeroutput>@BindingType</computeroutput> annotation. JBossWS does handle SOAP1.1 and SOAP1.2. Both come with or without MTOM flavours:</para><para><emphasis role="bold"> MTOM enabled service implementations </emphasis></para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.xop.doclit;
+
+<emphasis role="bold">import</emphasis> javax.ejb.Remote;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.jws.soap.SOAPBinding;
+<emphasis role="bold">import</emphasis> javax.xml.ws.BindingType;
+
+@Remote
+@WebService(targetNamespace = "http://org.jboss.ws/xop/doclit")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, parameterStyle = SOAPBinding.ParameterStyle.BARE)
+@BindingType(value="http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true") (1)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> MTOMEndpoint {
+
+ [...]
+}
+</screen><orderedlist><listitem><para> The MTOM enabled SOAP 1.1 binding ID </para></listitem></orderedlist><para><emphasis role="bold"> MTOM enabled clients </emphasis></para><para>Web service clients can use the same approach described above or rely on the <computeroutput>Binding</computeroutput> API to enable MTOM (Excerpt taken from the <computeroutput>org.jboss.test.ws.jaxws.samples.xop.doclit.XOPTestCase</computeroutput>):</para><screen xml:space="preserve">[...]
+Service service = Service.create(wsdlURL, serviceName);
+port = service.getPort(MTOMEndpoint.class);
+
+// enable MTOM
+binding = (SOAPBinding)((BindingProvider)port).getBinding();
+binding.setMTOMEnabled(<emphasis role="bold">true</emphasis>);
+
+</screen><para> </para><note><para><para><emphasis role="bold">Note</emphasis></para><para>You might as well use the JBossWS configuration templates to setup deployment defaults.</para></para></note></section>
+</section>
+<section id="JBossWS-NativeUserGuide_SwaRef"><title>SwaRef</title><para><ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html">WS-I Attachment Profile 1.0</ulink> defines mechanism to reference MIME attachment parts using <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2004-08-24.html#Refer...">swaRef</ulink>. In this mechanism the content of XML element of type wsi:swaRef is sent as MIME attachment and the element inside SOAP Body holds the reference to this attachment in the CID URI scheme as defined by <ulink url="http://www.ietf.org/rfc/rfc2111.txt">RFC 2111</ulink>.</para><section id="JBossWS-NativeUserGuide_Using_SwaRef_with_JAXWS_endpoints"><title>Using SwaRef with JAX-WS endpoints</title><para>JAX-WS endpoints delegate all marshalling/unmarshalling to the JAXB API. The most simple way to enable SwaRef encoding for <computeroutput>DataHandler</computeroutput> types is to annotate a payl!
oad bean with the <computeroutput>@XmlAttachmentRef</computeroutput> annotation as shown below:</para><screen xml:space="preserve">/**
+* Payload bean that will use SwaRef encoding
+*/
+@XmlRootElement
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DocumentPayload
+{
+ <emphasis role="bold">private</emphasis> DataHandler data;
+
+ <emphasis role="bold">public</emphasis> DocumentPayload()
+ {
+ }
+
+ <emphasis role="bold">public</emphasis> DocumentPayload(DataHandler data)
+ {
+ this.data = data;
+ }
+
+ @XmlElement
+ @XmlAttachmentRef
+ <emphasis role="bold">public</emphasis> DataHandler getData()
+ {
+ <emphasis role="bold">return</emphasis> data;
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setData(DataHandler data)
+ {
+ this.data = data;
+ }
+}
+</screen><para>With document wrapped endpoints you may even specify the <computeroutput>@XmlAttachmentRef</computeroutput> annotation on the service endpoint interface:</para><screen xml:space="preserve">@WebService
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> DocWrappedEndpoint
+{
+ @WebMethod
+ DocumentPayload beanAnnotation(DocumentPayload dhw, String test);
+
+ @WebMethod
+ @XmlAttachmentRef
+ DataHandler parameterAnnotation(@XmlAttachmentRef DataHandler data, String test);
+
+}
+</screen><para>The message would then refer to the attachment part by CID:</para><screen xml:space="preserve"><env:Envelope xmlns:env='<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>'><env:Header/><env:Body>
+ <ns2:parameterAnnotation xmlns:ns2='<ulink url="http://swaref.samples.jaxws.ws.test.jboss.org/">http://swaref.samples.jaxws.ws.test.jboss.org/</ulink>'>
+ <arg0>cid:0-1180017772935-32455963@ws.jboss.org</arg0>
+ <arg1>Wrapped test</arg1>
+ </ns2:parameterAnnotation></env:Body>
+</env:Envelope></screen></section>
+<section id="JBossWS-NativeUserGuide_Starting_from_WSDL"><title>Starting from WSDL</title><para>If you chose the contract first approach then you need to ensure that any element declaration that should use SwaRef encoding simply refers to wsi:swaRef schema type:</para><screen xml:space="preserve"><element name="data" type="wsi:swaRef"
+xmlns:wsi="<ulink url="http://ws-i.org/profiles/basic/1.1/xsd">http://ws-i.org/profiles/basic/1.1/xsd</ulink>"/>
+</screen><para>Any wsi:swaRef schema type would then be mapped to DataHandler.</para><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-NativeUserGuide_Standard_Annotations"><title>Standard Annotations</title><section id="JBossWS-NativeUserGuide_PostConstruct_and_PreDestroy_annotations"><title>PostConstruct and PreDestroy annotations</title><para>Users can use standard Java <emphasis role="bold">javax.annotation.PostConstruct</emphasis> and <emphasis role="bold">javax.annotation.PreDestroy</emphasis> annotations for service lifecycle notification on all POJO endpoints. Here's the sample POJO bean:</para><screen xml:space="preserve">@WebService(
+ serviceName = "EndpointService",
+ targetNamespace = "http://yourorganization.com/service",
+ endpointInterface="com.yourorganization.EndpointInterface"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> EndpointImpl
+{
+
+ @PostConstruct
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">void</emphasis> init()
+ {
+ // lifecycle method for initialization
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String msg)
+ {
+ <emphasis role="bold">return</emphasis> msg;
+ }
+
+ @PreDestroy
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">void</emphasis> cleanUp()
+ {
+ // lifecycle method for cleanup
+ }
+
+}
+</screen></section>
+</section>
+<section id="JBossWS-NativeUserGuide_JBossWSNative_JAXWS_Extensions"><title>JBossWS-Native JAX-WS Extensions</title><para>This section describes propriatary JBoss extensions to JAX-WS, provided for JBossWS-Native stack only. Please refer to the <link linkend="chap_JBossWS-UserGuide">common user guide</link> for further JBossWS Extensions.</para><para> </para><section id="JBossWS-NativeUserGuide_Proprietary_Annotations"><title>Proprietary Annotations</title><para>For the set of standard annotations, please have a look at <link linkend="chap_JBossWS-JAX-WSAnnotations">JAX-WS_Annotations</link>.</para><section id="JBossWS-NativeUserGuide_EndpointConfig"><title>EndpointConfig</title><screen xml:space="preserve">/**
+ * Defines an endpoint or client configuration.
+ * This annotation is valid on an endpoint implementaion bean or a SEI.
+ *
+ * @author Heiko.Braun(a)jboss.org
+ * @since 16.01.2007
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> EndpointConfig {
+
+ /**
+ * The optional config-name element gives the configuration name that must be present in
+ * the configuration given by element config-file.
+ *
+ * Server side default: Standard Endpoint
+ * Client side default: Standard Client
+ */
+ String configName() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The optional config-file element is a URL or resource name for the configuration.
+ *
+ * Server side default: standard-jaxws-endpoint-config.xml
+ * Client side default: standard-jaxws-client-config.xml
+ */
+ String configFile() <emphasis role="bold">default</emphasis> "";
+}
+</screen><para> </para></section>
+<section id="JBossWS-NativeUserGuide_Documentation"><title>Documentation</title><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.ws.annotation;
+
+/**
+ * Annotation to be used to add wsdl:documentation elements to the generated wsdl.
+ *
+ * @author alessio.soldano(a)jboss.org
+ * @since 15-Jan-2008
+ */
+(a)Target({ElementType.TYPE, ElementType.METHOD})
+(a)Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> Documentation
+{
+ <emphasis role="bold">public</emphasis> String content();
+}
+</screen></section>
+<section id="JBossWS-NativeUserGuide_SchemaValidation"><title>SchemaValidation</title><screen xml:space="preserve">/**
+ * This feature represents the use of schema validation with a
+ * web service.
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> SchemaValidation
+{
+ /**
+ * Optional property for the schema location. If this is not specified the schema
+ * will be attempted to extract from the WSDL.
+ *
+ * The syntax is the same as for schemaLocation attributes in instance documents: e.g, "http://www.example.com file_name.xsd".
+ */
+ String schemaLocation() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * Optional property for the error handler.
+ * If this is not specified the @{ValidationErrorHandler} will be used.
+ */
+ Class errorHandler() <emphasis role="bold">default</emphasis> StrictlyValidErrorHandler.class;
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis role="bold">default</emphasis> <emphasis role="bold">true</emphasis>;
+}
+</screen></section>
+<section id="JBossWS-NativeUserGuide_FastInfoset"><title>FastInfoset</title><screen xml:space="preserve">/**
+ * This feature represents the use of FastInfoset
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> FastInfoset {
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis role="bold">default</emphasis> <emphasis role="bold">true</emphasis>;
+}
+</screen></section>
+<section id="JBossWS-NativeUserGuide_JsonEncoding"><title>JsonEncoding</title><screen xml:space="preserve">/**
+ * This feature represents the use of JSON encoding
+ *
+ * @author Thomas.Diesler(a)jboss.com
+ * @since 29-Feb-2008
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> JsonEncoding {
+
+ /**
+ * Specifies if the feature is enabled or disabled
+ */
+ <emphasis role="bold">boolean</emphasis> enabled() <emphasis role="bold">default</emphasis> <emphasis role="bold">true</emphasis>;
+}
+</screen></section>
+</section>
+<section id="JBossWS-NativeUserGuide_Proprietary_WebServiceFeatures"><title>Proprietary WebServiceFeatures</title><section id="JBossWS-NativeUserGuide_Schema_validation_for_incomingoutgoing_messages"><title>Schema validation for incoming/outgoing messages</title><para>On the client, schema validation can be enabled using the SchemaValidationFeature</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.feature.SchemaValidationFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+SchemaValidationFeature feature = <emphasis role="bold">new</emphasis> SchemaValidationFeature(xsdURL.toString());
+MyTest port = service.getPort(MyTest.class, feature);
+</screen><para>You can explicitly set the schema location and the error handler. If the schema location is not set, the schema will be extracted from the WSDL.</para><para>The default error handler is strict and causes a SAX exception when the message does not conform to the schema.</para><para>The SchemaValidationFeature has an equivalent @SchemaValidation annotation that can be used on the endpoint.</para></section>
+<section id="JBossWS-NativeUserGuide_Support_for_FastInfoset"><title>Support for FastInfoset</title><para>On the client, FastInfoset can be enabled using the FastInfosetFeature</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.feature.FastInfosetFeature;
+
+Serviceservice = Service.create(wsdlURL, serviceName);
+FastInfosetFeature feature = <emphasis role="bold">new</emphasis> FastInfosetFeature();
+FastInfoset port = service.getPort(FastInfoset.class, feature);
+</screen><para>The FastInfosetFeature has an equivalent @FastInfoset annotation that can be used on the endpoint.</para></section>
+<section id="JBossWS-NativeUserGuide_Support_for_JSON_data_binding"><title>Support for JSON data binding</title><para>On the client, JSON data binding can be enabled using the JsonEncodingFeature</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.feature.JsonEncodingFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+JsonEncodingFeature feature = <emphasis role="bold">new</emphasis> JsonEncodingFeature();
+JsonPort port = service.getPort(JsonPort.class, feature);
+</screen><para>The JsonEncodingFeature has an equivalent @JsonEncoding annotation that can be used on the endpoint.</para></section>
+<section id="JBossWS-NativeUserGuide_Chunked_encoding_setup"><title>Chunked encoding setup</title><para>On the client, the chunked encoding can be disabled (it's enabled by default) or the chunks size can be configured using the ChunkedEncodingFeature</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.feature.ChunkedEncodingFeature;
+
+Service service = Service.create(wsdlURL, SERVICE_NAME);
+ChunkedEncodingFeature feature = <emphasis role="bold">new</emphasis> ChunkedEncodingFeature(<emphasis role="bold">false</emphasis>); //false to disable
+MyPort port = service.getPort(MyPort.class, feature);
+</screen><para>Alternatively, the <emphasis role="bold">StubExt.PROPERTY_CHUNKED_ENCODING_SIZE</emphasis> property can be used to set the chunk size in the request context (size 0 disables chunked encoding).</para></section>
+<section id="JBossWS-NativeUserGuide_Disable_Xerces_Deferred_Node_Expansion"><title>Disable Xerces Deferred Node Expansion</title><para>To optimise the parsing of messages Xerces has a feature called deferred node expansion which defers the expansion of the nodes until they are actually accessed. For messages where not all of the nodes will be visited this improves performance but the cost is increased memory overheads which can be considerable for very large messages.</para><para>To disable this feature the following system property can be set so that the nodes are eagerly expanded.</para><screen xml:space="preserve"> -Dorg.jboss.ws.disable_deferred_node_expansion=true</screen></section>
+</section>
+<section id="JBossWS-NativeUserGuide_Deployment_descriptor_attributes"><title>Deployment descriptor attributes</title><section id="JBossWS-NativeUserGuide_JSE_Endpoints"><title>JSE Endpoints</title><para>The following is taken from <ulink url="http://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk/src/main/r...">http://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk/src/main/r...</ulink> and shows an excerpt of the jboss-web_5_0.dtd The most important bits are:</para><itemizedlist><listitem><para> <computeroutput>config-name</computeroutput>: JBossWS endpoint config name (see <link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS - JAX-WS Endpoint Configuration</link>) </para></listitem><listitem><para> <computeroutput>config-file</computeroutput>: JBossWS endpoint config file </para></listitem><listitem><para> <computeroutput>wsdl-publish-location</computeroutput>: Where to publish the runtime !
gnerated WSDL </para></listitem></itemizedlist><screen xml:space="preserve"><!--
+Runtime information about a web service.
+
+wsdl-publish-location is optionally used to specify
+where the final wsdl and any dependent files should be stored. This location
+resides on the file system from which deployment is initiated.
+
+-->
+<!ELEMENT webservice-description ( webservice-description-name, config-name?,
+ config-file?, wsdl-publish-location? )>
+
+<!--
+Unique name of a webservice within a module
+-->
+<!ELEMENT webservice-description-name ( #PCDATA )>
+
+<!--
+file: URL of a directory to which a web-service-description's wsdl should be
+published during deployment. Any required files will be published to this
+directory, preserving their location relative to the module-specific
+wsdl directory(META-INF/wsdl or WEB-INF/wsdl).
+
+Example :
+
+ For an ejb.jar whose webservices.xml wsdl-file element contains
+ META-INF/wsdl/a/Foo.wsdl
+
+ <wsdl-publish-location>file:/home/user1/publish
+ </wsdl-publish-location>
+
+ The final wsdl will be stored in /home/user1/publish/a/Foo.wsdl
+
+-->
+<!ELEMENT wsdl-publish-location ( #PCDATA )></screen><para> </para></section>
+<section id="JBossWS-NativeUserGuide_EJB3_endpoints"><title>EJB3 endpoints</title><para>EJB deployment descriptor attributes are quite the same. You can specify a top level <computeroutput>webservices</computeroutput> element along with your ejb declaration that allows you to override certain deployment aspects. The following excerpt is taken from <ulink url="https://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk/src/main/...">https://anonsvn.jboss.org/repos/jbossas/projects/metadata/trunk/src/main/...</ulink></para><para>In addition to the default properties that are customizable like in JSE deployments, the EJB descriptor allows you to specify:</para><itemizedlist><listitem><para> <computeroutput>context-root</computeroutput>: A custom web context root. Applies to all beans in this deployment unit </para></listitem></itemizedlist><screen xml:space="preserve"><!ELEMENT webservices (context-root?, webservice-descri!
ption*)>
+
+<!-- The context-root element specifies the context root of the web
+application that the EJB service endpoints are deployed to.
+If it is not specified it will be derived from the deployment short name.
+-->
+<!ELEMENT context-root (#PCDATA)>
+
+<!--
+Runtime information about a web service.
+wsdl-publish-location is optionally used to specify
+where the final wsdl and any dependent files should be stored. This location
+resides on the file system from which deployment is initiated.
+-->
+<!ELEMENT webservice-description ( webservice-description-name, config-name?,
+ config-file?, wsdl-publish-location? )></screen><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-NativeUserGuide_Appendix_A"><title>Appendix A</title><para><link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS - JAX-WS Endpoint Configuration</link></para><para><link linkend="chap_JBossWS-JAX-WSClientConfiguration">JBossWS - JAX-WS Client Configuration</link></para><para><link linkend="chap_JBossWS-JAX-WSAnnotations">JBossWS - JAX-WS Annotations</link></para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-NativeWS-AddressingTutorial.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-NativeWS-AddressingTutorial"><title>JBossWS-NativeWS-AddressingTutorial</title><para> <link linkend="chap_JBossWS-NativeUserGuide">JBossWS - Native User Guide</link> comes with support for <ulink url="http://www.w3.org/TR/ws-addr-core/">WS-Addressing 1.0</ulink>. In this sample we will show how to create a client and endpoint communicating each with other using this feature.</para><para>Creating a WS-Addressing based service and client is very simple. The user needs to create a regular JAX-WS service and client first. The last step is to configure the addressing on both sides.</para><para/><section id="JBossWS-NativeWS-AddressingTutorial_The_service"><title>The service</title><para>We will start with the following endpoint implementation (bottom-up approach):</para><screen xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para>The endpoint implements the following endpoint interface:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> ServiceIface
+{
+ @WebMethod
+ String sayHello();
+}
+</screen><para>Let's say that compiled endpoint and interface classes are located in directory <emphasis role="bold">/home/username/wsa/native/classes</emphasis>. Our next step is to generate JAX-WS artifacts and WSDL that will be part of endpoint archive.</para><para> </para></section>
+<section id="JBossWS-NativeWS-AddressingTutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating WSDL and JAX-WS Endpoint Artifacts</title><para>We will use wsprovide commandline tool to generate WSDL and JAX-WS artifacts. Here's the command:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsa/native/classes \
+ --output=/home/username/wsa/native/wsprovide/generated/classes \
+ --resource=/home/username/wsa/native/wsprovide/generated/wsdl \
+ --source=/home/username/wsa/native/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsa/native/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+SayHello.class SayHelloResponse.class
+
+# java sources
+ls /home/username/wsa/native/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+SayHello.java SayHelloResponse.java
+
+# contract artifacts
+ls /home/username/wsa/native/wsprovide/generated/wsdl/
+AddressingService.wsdl
+</screen><para>All aforementioned generated artifacts will be part of endpoint archive. But before we will create the endpoint archive we need to reference generated WSDL from endpoint. To achieve that we will use wsdlLocation annotation attribute. Here's the updated endpoint implementation before packaging it to the war file:</para><screen xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para>Created endpoint war archive consists of the following entries:</para><screen xml:space="preserve">jar -tvf jaxws-samples-wsa.war
+ 0 Tue Apr 22 14:28:32 CEST 2008 META-INF/
+ 106 Tue Apr 22 14:28:30 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/
+ 593 Tue Apr 22 14:28:30 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 22 14:28:22 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 22 14:28:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 22 14:28:28 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/
+ 374 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceIface.class
+ 892 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceImpl.class
+ 0 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+ 703 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHello.class
+ 1067 Tue Apr 22 14:28:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHelloResponse.class
+ 0 Tue Apr 22 14:28:32 CEST 2008 WEB-INF/wsdl/
+ 1731 Tue Apr 22 14:28:30 CEST 2008 WEB-INF/wsdl/AddressingService.wsdl
+</screen><para>The content of web.xml file is:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><web-app
+ version="2.5" xmlns="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink> <ulink url="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd</ulink>">
+ <servlet>
+ <servlet-name>AddressingService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>AddressingService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app></screen></section>
+<section id="JBossWS-NativeWS-AddressingTutorial_Writing_Regular_JAXWS_Client"><title>Writing Regular JAX-WS Client</title><para>The following is the regular JAX-WS client using endpoint interface to lookup the webservice:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> AddressingTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ // create service
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
+
+ // invoke method
+ proxy.sayHello();
+ }
+
+}
+</screen><para>Now we have both endpoint and client implementation but without WS-Addressing in place. Our next goal is to turn on the WS-Addressing feature.</para><para> </para></section>
+<section id="JBossWS-NativeWS-AddressingTutorial_Turning_on_WSAddressing_10"><title>Turning on WS-Addressing 1.0</title><para>In order to turn on WS-Addressing in JBossWS-Native integration the last two steps are remaining:</para><itemizedlist><listitem><para>annotate service endpoint with @Addressing annotation</para></listitem><listitem><para>modify client to configure WS-Addressing using JAX-WS webservice feature</para></listitem></itemizedlist><para> </para><section id="JBossWS-NativeWS-AddressingTutorial_Updating_Endpoint_Code_to_Configure_WSAddressing"><title>Updating Endpoint Code to Configure WS-Addressing</title><para>Now we need to update endpoint implementation to configure WS-Addressing. Here's the updated endpoint code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.xml.ws.soap.Addressing;
+
+@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+@Addressing(enabled=true, required=<emphasis role="bold">true</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para>As users can see we added JAX-WS 2.1 <emphasis role="bold">Addressing</emphasis> annotation to configure WS-Addressing. The next step is to repackage the endpoint archive to apply this change.</para><para> </para></section>
+<section id="JBossWS-NativeWS-AddressingTutorial_Updating_Client_Code_to_Configure_WSAddressing"><title>Updating Client Code to Configure WS-Addressing</title><para>Now we need to update client implementation as well to configure WS-Addressing. Here's the updated client code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> javax.xml.ws.soap.AddressingFeature;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> AddressingTestCase
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ // construct proxy
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class, <emphasis role="bold">new</emphasis> AddressingFeature());
+ // invoke method
+ assertEquals("Hello World!", proxy.sayHello());
+ }
+
+}
+</screen><para>And that's all. Now we have both JAX-WS client and endpoint communicating each other using WS-Addressing feature.</para><para> </para></section>
+</section>
+<section id="JBossWS-NativeWS-AddressingTutorial_Sample_Sources"><title>Sample Sources</title><para>All sources from this tutorial are part of JBossWS-Native distribution.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-NativeWS-ReliableMessagingTutorial.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,333 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-NativeWS-ReliableMessagingTutorial"><title>JBossWS-NativeWS-ReliableMessagingTutorial</title><para>JBossWS-Native comes with support for both <ulink url="http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf">WS-RM 1.0</ulink> and <ulink url="http://docs.oasis-open.org/ws-rx/wsrm/v1.1/wsrm.pdf">WS-RM 1.1</ulink>. In this sample we will show how to create client and endpoint communicating each other using WS-RM 1.1 The sample uses <ulink url="http://schemas.xmlsoap.org/ws/2004/09/policy/">WS-Policy</ulink> specification to configure WS-RM.</para><para>Creating the WS-RM based service and client is very simple. User needs to create regular JAX-WS service and client first. The last step is to configure WSRM.</para><para/><para> </para><section id="JBossWS-NativeWS-ReliableMessagingTutorial_The_service"><title>The service</title><para>We will start with the following endpoint implementation (bottom-up ap!
proach):</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl"
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>Let's say that compiled endpoint class is in directory <emphasis role="bold">/home/username/wsrm/native/classes</emphasis>. Our next step is to generate JAX-WS artifacts and WSDL.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating WSDL and JAX-WS Endpoint Artifacts</title><para>We will use wsprovide commandline tool to generate WSDL and JAX-WS artifacts. Here's the command:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsrm/native/classes \
+ --output=/home/username/wsrm/native/wsprovide/generated/classes \
+ --resource=/home/username/wsrm/native/wsprovide/generated/wsdl \
+ --source=/home/username/wsrm/native/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsrm/native/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.class EchoResponse.class Ping.class
+
+# java sources
+ls /home/username/wsrm/native/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.java EchoResponse.java Ping.java
+
+# contract artifacts
+ls /home/username/wsrm/native/wsprovide/generated/wsdl/
+SimpleService.wsdl
+</screen><para>All aforementioned generated artifacts will be part of endpoint archive. The endpoint archive consists of the following files:</para><screen xml:space="preserve">jar -tvf jaxws-samples-wsrm.war
+ 0 Tue Apr 15 19:06:14 CEST 2008 META-INF/
+ 106 Tue Apr 15 19:06:12 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/
+ 591 Tue Apr 15 19:05:42 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+ 1385 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
+ 995 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
+ 1043 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
+ 679 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/wsdl/
+ 2934 Tue Apr 15 19:05:36 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
+</screen><para>The content of web.xml file is:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><web-app
+ version="2.5" xmlns="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink> <ulink url="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd</ulink>">
+ <servlet>
+ <servlet-name>SimpleService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>SimpleService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app></screen></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Generating_JAXWS_Client_Artifacts"><title>Generating JAX-WS Client Artifacts</title><para>Before we will write regular JAX-WS client we need to generate client artifacts from WSDL. Here's the command to achieve that:</para><screen xml:space="preserve">cd $JBOSS_HOME
+
+./wsconsume.sh --keep \
+ --package=org.jboss.test.ws.jaxws.samples.wsrm.generated \
+ --output=/home/username/wsrm/native/wsconsume/generated/classes \
+ --source=/home/username/wsrm/native/wsconsume/generated/src \
+ /home/username/wsrm/native/wsprovide/generated/wsdl/SimpleService.wsdl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsrm/native/wsconsume/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.class EchoResponse.class ObjectFactory.class package-info.class Ping.class SimpleService.class SimpleService_Service.class
+
+# java sources
+ls /home/username/wsrm/native/wsconsume/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.java EchoResponse.java ObjectFactory.java package-info.java Ping.java SimpleService.java SimpleService_Service.java
+</screen><para>Now the last step is to write the regular JAX-WS client using generated artifacts.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Writing_Regular_JAXWS_Client"><title>Writing Regular JAX-WS Client</title><para>The following is the regular JAX-WS client using generated artifacts:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+ }
+
+}
+</screen><para>Now we have both endpoint and client implementation but without WSRM in place. Our next goal is to turn on WS-RM feature.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Turning_on_WSRM_11"><title>Turning on WS-RM 1.1</title><para>In order to turn on WS-RM in JBossWS-Native four steps are necessary:</para><itemizedlist><listitem><para> extend WSDL with WS-Policy containing both WSRM and WS-Addressing policy </para></listitem><listitem><para> provide both endpoint and client jaxws configuration files </para></listitem><listitem><para> update endpoint implementation to use endpoint jaxws file </para></listitem><listitem><para> update client to use client jaxws file and close the sequence</para></listitem></itemizedlist><para> </para><para> </para><section id="JBossWS-NativeWS-ReliableMessagingTutorial_Extending_WSDL_Using_WSPolicy"><title>Extending WSDL Using WS-Policy</title><para>To activate WSRM we need to extend WSDL with WSRM and addressing policy. Here is how it looks like:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<definitions name='SimpleService' targetNamespace='<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>' xmlns='<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>' xmlns:soap='<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>' xmlns:tns='<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>' xmlns:xsd='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>' xmlns:wsp="<ulink url="http://schemas.xmlsoap.org/ws/2004/09/policy">http://schemas.xmlsoap.org/ws/2004/09/policy</ulink>">
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <!-- Created WS-Policy with WSRM addressing assertions -->
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <wsp:UsingPolicy/>
+ <wsp:Policy
+ wsu:Id="wsrm11policy"
+ xmlns:wsu="<ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...</ulink>">
+ <wsp:All>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <ns1:RMAssertion xmlns:ns1="<ulink url="http://docs.oasis-open.org/ws-rx/wsrmp/200702">http://docs.oasis-open.org/ws-rx/wsrmp/200702</ulink>"/>
+ <ns2:UsingAddressing xmlns:ns2="<ulink url="http://www.w3.org/2006/05/addressing/wsdl">http://www.w3.org/2006/05/addressing/wsdl</ulink>"/>
+ </wsp:All>
+ </wsp:ExactlyOne>
+ </wsp:All>
+ </wsp:Policy><types>
+ <xs:schema targetNamespace='<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>' version='1.0' xmlns:tns='<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>' xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+ <xs:element name='echo' type='tns:echo'/>
+ <xs:element name='echoResponse' type='tns:echoResponse'/>
+ <xs:element name='ping' type='tns:ping'/>
+ <xs:complexType name='ping'>
+ <xs:sequence/>
+ </xs:complexType>
+ <xs:complexType name='echo'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='arg0' type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name='echoResponse'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='return' type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema></types><message name='SimpleService_echo'>
+ <part element='tns:echo' name='echo'/></message><message name='SimpleService_echoResponse'>
+ <part element='tns:echoResponse' name='echoResponse'/></message><message name='SimpleService_ping'>
+ <part element='tns:ping' name='ping'/></message><portType name='SimpleService'>
+ <operation name='echo' parameterOrder='echo'>
+ <input message='tns:SimpleService_echo'/>
+ <output message='tns:SimpleService_echoResponse'/>
+ </operation>
+ <operation name='ping'>
+ <input message='tns:SimpleService_ping'/>
+ </operation></portType><binding name='SimpleServiceBinding' type='tns:SimpleService'>
+ <!-- - - - - - - - - - - - - - - - - - - - -->
+ <!-- Associated WS-Policy with the binding -->
+ <!-- - - - - - - - - - - - - - - - - - - - -->
+ <wsp:PolicyReference URI="#wsrm11policy"/>
+ <soap:binding style='document' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation>
+ <operation name='ping'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ </operation></binding><service name='SimpleService'>
+ <port binding='tns:SimpleServiceBinding' name='SimpleServicePort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</definitions>
+</screen><para>We added <emphasis role="bold">wsp:UsingPolicy</emphasis>, <emphasis role="bold">wsp:Policy</emphasis> and <emphasis role="bold">wsp:PolicyReference</emphasis> elements to WSDL.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Providing_Endpoint_and_Client_JAXWS_Configuration_Files"><title>Providing Endpoint and Client JAX-WS Configuration Files</title><para>In order to activate WSRM in JBossWS-Native integration user have to provide both endpoint and client jaxws configuration files containing both addressing and WSRM handlers in the processing chain.</para><para>The endpoint jaxws configuration file, in our case we will call it <emphasis role="bold">wsrm-jaxws-endpoint-config.xml</emphasis> has the following content:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><jaxws-config
+ xmlns="urn:jboss:jaxws-config:2.0"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Standard WSRM Endpoint</config-name>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ <javaee:handler>
+ <javaee:handler-name>WSRM Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.wsrm.jaxws.RMServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </endpoint-config></jaxws-config>
+</screen><para>The client jaxws configuration file, in our case we will call it <emphasis role="bold">wsrm-jaxws-client-config.xml</emphasis> has the following content:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><jaxws-config
+ xmlns="urn:jboss:jaxws-config:2.0"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xmlns:javaee="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <client-config>
+ <config-name>Standard Anonymous WSRM Client</config-name>
+ <reliable-messaging>
+ <message-retransmission attempts="50" interval="10" timeout="10"/>
+ </reliable-messaging>
+ <post-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>WSAddressing Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.addressing.jaxws.WSAddressingClientHandler</javaee:handler-class>
+ </javaee:handler>
+ <javaee:handler>
+ <javaee:handler-name>WSRM Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.ws.extensions.wsrm.jaxws.RMClientHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </post-handler-chains>
+ </client-config></jaxws-config>
+</screen><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>Both client and endpoint jaxws configuration files are available in native WSRM tests. Users can copy them from there.</emphasis></para></para></note><para>The next step is to include jaxws endpoint configuration file in META-INF directory of the endpoint archive.</para><screen xml:space="preserve">jar -tvf jaxws-samples-wsrm.war
+ 0 Tue Apr 15 19:06:14 CEST 2008 META-INF/
+ 106 Tue Apr 15 19:06:12 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/
+ 591 Tue Apr 15 19:05:42 CEST 2008 WEB-INF/web.xml
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/classes/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Apr 15 19:04:50 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
+ 0 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+ 1385 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
+ 995 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
+ 1043 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
+ 679 Tue Apr 15 19:05:10 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
+ 0 Tue Apr 15 19:06:14 CEST 2008 WEB-INF/wsdl/
+ 2934 Tue Apr 15 19:05:36 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
+ 2033 Tue Apr 15 19:05:52 CEST 2008 META-INF/wsrm-jaxws-endpoint-config.xml
+</screen><para>What about client side, the client jaxws configuration file must be available on the client classpath, in our case it will be available as <emphasis role="bold">META-INF/wsrm-jaxws-client-config.xml</emphasis> resource.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Updating_Endpoint_Code_to_Reference_Custom_JAXWS_Config_File"><title>Updating Endpoint Code to Reference Custom JAX-WS Config File</title><para>Now we need to update endpoint implementation to reference custom JAX-WS configuration file. Here's the updated endpoint code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+<emphasis role="bold">import</emphasis> org.jboss.ws.annotation.EndpointConfig;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+@EndpointConfig
+(
+ configFile = "META-INF/wsrm-jaxws-endpoint-config.xml",
+ configName = "Standard WSRM Endpoint"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>As users can see we added JBossWS proprietary <emphasis role="bold">EndpointConfig</emphasis> annotation to reference the endpoint config.</para><para> </para></section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Updating_Client_Code_to_Reference_Custom_JAXWS_Config_File_and_Close_the_Sequence"><title>Updating Client Code to Reference Custom JAX-WS Config File and Close the Sequence</title><para>Now we need to update client implementation as well to reference custom JAX-WS configuration file. We will also add the call to close the created sequence there. Here's the updated client code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.jboss.ws.core.StubExt;
+<emphasis role="bold">import</emphasis> org.jboss.ws.extensions.wsrm.api.RMProvider;
+<emphasis role="bold">import</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+ ((StubExt)proxy).setConfigName("Standard Anonymous WSRM Client", "META-INF/wsrm-jaxws-client-config.xml");
+
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+ ((RMProvider)proxy).closeSequence();
+ }
+
+}
+</screen><para>And that's all. Now user have both endpoint and client using WS-RM 1.1 when communicating each other.</para><para> </para></section>
+</section>
+<section id="JBossWS-NativeWS-ReliableMessagingTutorial_Sample_Sources"><title>Sample Sources</title><para>All sources from this tutorial are part of JBossWS-Native distribution.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-QuickStart.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-QuickStart"><title>JBossWS-QuickStart</title><para/><para> </para><section id="JBossWS-QuickStart_Right_on"><title>Right on'</title><para>JBossWS uses the JBoss application server as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the user guide.</para><para>In the following sections we will explore the samples that ship with the JBossWS distribution. They provide a build structure based on Ant to get you started quickly.</para></section>
+<section id="JBossWS-QuickStart_Developing_web_service_implementations"><title>Developing web service implementations</title><para>JAX-WS does leverage <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">JDK 5 annotations</ulink> in order to express web service meta data on Java components and to describe the mapping between Java data types and XML. When developing web service implementations you need to decide whether you are going start with an abstract contract (<ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink>) or a Java component.</para><para>If you are in charge to provide the service implementation, then you are probably going to start with the implementation and derive the abstract contract from it. You are probably not even getting in touch with the WSDL unless you hand it to 3rd party clients. For this reason we are going to look at a service implementation that leverages <ulink url="http://jcp.org/en/jsr/detail?id=181">JSR-181 annot!
ations</ulink>.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>Even though detailed knowledge of web service meta data is not required, it will definitely help if you make yourself familiar with it. For further information see</para><itemizedlist><listitem><para> <ulink url="http://jcp.org/en/jsr/detail?id=181">Web service meta data (JSR-181)</ulink> </para></listitem><listitem><para> <ulink url="http://java.sun.com/webservices/jaxb/">Java API for XML binding (JAXB)</ulink></para></listitem></itemizedlist></para></note><para>When starting from Java you must provide the service implementation. A valid endpoint implementation class must meet the following requirements:</para><itemizedlist><listitem><para> It <emphasis>must</emphasis> carry a <computeroutput>javax.jws.WebService</computeroutput> annotation (see JSR 181) </para></listitem><listitem><para> All method parameters and return types <emphasis>must</emphasis> be compatible with the JAXB !
2.0 </para></listitem></itemizedlist><para>Let's look at a sam!
ple EJB3
component that is going to be exposed as a web service. (This is based on the Retail example).</para><para>Don't be confused with the EJB3 annotation <computeroutput>@Stateless</computeroutput>. We concentrate on the <computeroutput>@WebService</computeroutput> annotation for now.</para><para><emphasis role="bold">The service implementation class</emphasis></para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis> javax.ejb.Stateless;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.soap.SOAPBinding;
+
+@Stateless (1)
+@WebService( (2)
+ name="ProfileMgmt",
+ targetNamespace = "http://org.jboss.ws/samples/retail/profile",
+ serviceName = "ProfileMgmtService")
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) (3)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ProfileMgmtBean {
+
+ @WebMethod (4)
+ <emphasis role="bold">public</emphasis> DiscountResponse getCustomerDiscount(DiscountRequest request) {
+ <emphasis role="bold">return</emphasis> <emphasis role="bold">new</emphasis> DiscountResponse(request.getCustomer(), 10.00);
+ }
+}
+
+</screen><orderedlist><listitem><para> We are using a stateless session bean implementation </para></listitem><listitem><para> Exposed a web service with an explicit namespace </para></listitem><listitem><para> It's a doc/lit bare endpoint </para></listitem><listitem><para> And offers an 'getCustomerDiscount' operation </para></listitem></orderedlist><para> <emphasis role="bold"> What about the payload? </emphasis></para><para>The method parameters and return values are going to represent our XML payload and thus require being compatible with <ulink url="http://java.sun.com/webservices/jaxb/">JAXB2</ulink>. Actually you wouldn't need any JAXB annotations for this particular example, because JAXB relies on meaningful defaults. For the sake of documentation we put the more important ones here.</para><para>Take a look at the request parameter:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlAccessType;
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlAccessorType;
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlType;
+
+<emphasis role="bold">import</emphasis> org.jboss.test.ws.jaxws.samples.retail.Customer;
+
+(a)XmlAccessorType(XmlAccessType.field)
+@XmlType( (1)
+ name = "discountRequest",
+ namespace="http://org.jboss.ws/samples/retail/profile",
+ propOrder = { "customer" }
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DiscountRequest {
+
+ <emphasis role="bold">protected</emphasis> Customer customer;
+
+ <emphasis role="bold">public</emphasis> DiscountRequest() {
+ }
+
+ <emphasis role="bold">public</emphasis> DiscountRequest(Customer customer) {
+ this.customer = customer;
+ }
+
+ <emphasis role="bold">public</emphasis> Customer getCustomer() {
+ <emphasis role="bold">return</emphasis> customer;
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setCustomer(Customer value) {
+ this.customer = value;
+ }
+
+}
+
+</screen><orderedlist><listitem><para>In this case we use <computeroutput>@XmlType</computeroutput> to specify an XML complex type name and override the namespace. </para></listitem></orderedlist><para> </para><variablelist/><section id="JBossWS-QuickStart_Deploying_service_implementations"><title>Deploying service implementations</title><para>Service deployment basically depends on the implementation type. As you may already know web services can be implemented as EJB3 components or plain old Java objects. This quick start leverages EJB3 components in all examples, thats why we are going to look at this case in the next sections.</para><para> </para><para><emphasis role="bold"> EJB3 services </emphasis></para><para>Simply wrap up the service implementation class, the endpoint interface and any custom data types in a JAR and drop them in the <computeroutput>deploy</computeroutput> directory. No additional deployment descriptors required. Any meta data required for the dep!
loyment of the actual web service is taken from the annotations provided on the implementation class and the service endpoint interface. JBossWS will intercept that EJB3 deployment (the bean will also be there) and create an HTTP endpoint at deploy-time:</para><para> </para><para><emphasis role="bold">The JAR package structure</emphasis></para><screen xml:space="preserve">jar -tf jaxws-samples-retail.jar
+
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtBean.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class
+</screen><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>If the deployment was successful you should be able to see your endpoint at <ulink url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink></emphasis></para><para> </para></para></note></section>
+</section>
+<section id="JBossWS-QuickStart_Consuming_web_services"><title>Consuming web services</title><para>When creating web service clients you would usually start from the WSDL. JBossWS ships with a set of tools to generate the required JAX-WS artefacts to build client implementations. In the following section we will look at the most basic usage patterns. For a more detailed introductoin to web service client please consult the <ulink url="http://community.jboss.org/docs/DOC-13972">user guide</ulink>.</para><para> </para><para> </para><para><emphasis role="bold">Using wsconsume </emphasis></para><para> </para><para>The <link linkend="chap_JBossWS-wsconsume">wsconsume tool</link> is used to consume the abstract contract (WSDL) and produce annotated Java classes (and optionally sources) that define it. We are going to start with the WSDL from our retail example (<link linkend="JBossWS-QuickStart_Profile_MgmtService">ProfileMgmtService.wsdl</link>). For a detailed tool reference!
you need to consult the user guide.</para><screen xml:space="preserve">wsconsume is a command line tool that generates
+portable JAX-WS artifacts from a WSDL file.
+
+usage: org.jboss.ws.tools.jaxws.command.wsconsume [options] <wsdl-url>
+
+options:
+ -h, --help Show this help message
+ -b, --binding=<file> One or more JAX-WS or JAXB binding files
+ -k, --keep Keep/Generate Java source
+ -c --catalog=<file> Oasis XML Catalog file for entity resolution
+ -p --package=<name> The target package for generated source
+ -w --wsdlLocation=<loc> Value to use for @WebService.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces
+</screen><para>Let's try it on our retail sample:</para><screen xml:space="preserve">~./wsconsume.sh -k
+-p org.jboss.test.ws.jaxws.samples.retail.profile ProfileMgmtService.wsdl (1)
+
+org/jboss/test/ws/jaxws/samples/retail/profile/Customer.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.java
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.java
+
+</screen><orderedlist><listitem><para> As you can see we did use the <computeroutput>-p</computeroutput> switch to specify the package name of the generated sources. </para></listitem></orderedlist><para> </para><para><emphasis role="bold"> The generated artifacts explained </emphasis></para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> File </entry><entry> Purpose </entry></row></thead><tbody><row><entry>ProfileMgmt.java</entry><entry>Service Endpoint Interface</entry></row><row><entry>Customer.java</entry><entry>Custom data type</entry></row><row><entry>Discount*.java</entry><entry>Custom data type</entry></row><row><entry>ObjectFactory.java</entry><entry>JAXB XML Registry</entry></row><row><entry>package-info.java</entry><entry>Holder for JAXB package annotations</entry></row><row><entry>ProfileMgmtService.java</entry><entry>Service factory</entry></row></tbody></tgroup></informaltable><para>B!
asically <computeroutput>wsconsume</computeroutput> generates all custom data types (JAXB annotated classes), the service endpoint interface and a service factory class. We will look at how these artifacts can be used the build web service client implementations in the next section.</para><para> </para><bridgehead id="Constructing_a_service_stub">Constructing a service stub</bridgehead><para>Web service clients make use of a service stubs that hide the details of a remote web service invocation. To a client application a WS invocation just looks like an invocation of any other business component. In this case the service endpoint interface acts as the business interface. JAX-WS does use a service factory class to construct this as particular service stub:</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+
+Service service = Service.create( (1)
+ <emphasis role="bold">new</emphasis> URL("http://example.org/service?wsdl"),
+ <emphasis role="bold">new</emphasis> QName("MyService")
+);
+ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); (2)
+
+// do something with the service stub here... (3)
+</screen><orderedlist><listitem><para> Create a service factory using the WSDL location and the service name </para></listitem><listitem><para> Use the tool created service endpoint interface to build the service stub </para></listitem><listitem><para> Use the stub like any other business interface </para></listitem></orderedlist><para> </para><para> </para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><note><para><para><emphasis>The creation of the service stub is quite costly. You should take care that it gets reused by your application code (However <emphasis role="bold">it's not thread safe</emphasis>). Within a EE5 environment you might want to investigate the <computeroutput>@WebServiceRef</computeroutput> functionality.</emphasis></para><para> </para></para></note></section>
+<section id="JBossWS-QuickStart_Appendix"><title>Appendix</title><section id="JBossWS-QuickStart_Profile_MgmtService"><title>ProfileMgmtService.wsdl</title><screen xml:space="preserve"><definitions
+ name='ProfileMgmtService'
+ targetNamespace='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns='<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>'
+ xmlns:ns1='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:soap='<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>'
+ xmlns:tns='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xsd='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+
+ <types>
+
+ <xs:schema targetNamespace='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ version='1.0' xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+ <xs:complexType name='customer'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='creditCardDetails' type='xs:string'/>
+ <xs:element minOccurs='0' name='firstName' type='xs:string'/>
+ <xs:element minOccurs='0' name='lastName' type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema>
+
+ <xs:schema
+ targetNamespace='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ version='1.0'
+ xmlns:ns1='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:tns='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+
+ <xs:import namespace='<ulink url="http://org.jboss.ws/samples/retail'/">http://org.jboss.ws/samples/retail'/</ulink>>
+ <xs:element name='getCustomerDiscount'
+ nillable='true' type='tns:discountRequest'/>
+ <xs:element name='getCustomerDiscountResponse'
+ nillable='true' type='tns:discountResponse'/>
+ <xs:complexType name='discountRequest'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='customer' type='ns1:customer'/>
+
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name='discountResponse'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='customer' type='ns1:customer'/>
+ <xs:element name='discount' type='xs:double'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema>
+
+ </types>
+
+ <message name='ProfileMgmt_getCustomerDiscount'>
+ <part element='tns:getCustomerDiscount' name='getCustomerDiscount'/>
+ </message>
+ <message name='ProfileMgmt_getCustomerDiscountResponse'>
+ <part element='tns:getCustomerDiscountResponse'
+ name='getCustomerDiscountResponse'/>
+ </message>
+ <portType name='ProfileMgmt'>
+ <operation name='getCustomerDiscount'
+ parameterOrder='getCustomerDiscount'>
+
+ <input message='tns:ProfileMgmt_getCustomerDiscount'/>
+ <output message='tns:ProfileMgmt_getCustomerDiscountResponse'/>
+ </operation>
+ </portType>
+ <binding name='ProfileMgmtBinding' type='tns:ProfileMgmt'>
+ <soap:binding style='document'
+ transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='getCustomerDiscount'>
+ <soap:operation soapAction=''/>
+ <input>
+
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation>
+ </binding>
+ <service name='ProfileMgmtService'>
+ <port binding='tns:ProfileMgmtBinding' name='ProfileMgmtPort'>
+
+ <soap:address
+ location='<ulink url="http://">http://</ulink><HOST>:<PORT>/jaxws-samples-retail/ProfileMgmtBean'/>
+ </port>
+ </service>
+</definitions></screen><para> </para> </section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Recordsmanagement.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Recordsmanagement"><title>JBossWS-Recordsmanagement</title><para>JBossWS records' collection and management system gives administrators a means of performing custom analysis of their webservice traffic as well as exporting communication logs.</para><para/><para> </para><section id="JBossWS-Recordsmanagement_What_is_recorded"><title>What is recorded</title><para>Each record is basically composed of a message plus additional information; here are the current record attributes:</para><itemizedlist><listitem><para> Creation date </para></listitem><listitem><para> Source host </para></listitem><listitem><para> Destination host </para></listitem><listitem><para> Message type (in/out) </para></listitem><listitem><para> Invoked endpoint operation </para></listitem><listitem><para> Message envelope (including both soap:header and soap:body for SOAP messages) </para></listitem><listitem><para> Http headers </para></list!
item><listitem><para> Record group ID (allowing records belonging to the same message flow to be linked together) </para></listitem></itemizedlist><para>Of course records may also have meaningful values for a subset of the afore mentioned record attributes.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Use_cases"><title>Use cases</title><para>What are records useful for? In spite of <link linkend="chap_JBossWS-Endpointmanagement">endpoint metrics</link> that provide response time information and counts of invocations, records provide users with rich data about the content of the exchanged messages and their sender/receiver. The record system allows fine grained management and is customizable according to the users need; some of the use cases supported by the default configuration are:</para><itemizedlist><listitem><para> Logging request and response messages: being able to record messages received from and sent to a given service consumer without stopping the provider may be really useful. You just need to set the <emphasis>recording</emphasis> attribute of their endpoint's LogRecorder to true. The added value of this logging solution comes from the use of filters through which messages coming from a given address and related to a gi!
ven wsdl operation only can be logged. </para></listitem><listitem><para> Accountability: service providers may want to know which consumers are actually hitting a given service. This can be done for example using the <emphasis>getClientHosts</emphasis> functionality of the MemoryBufferRecorder once it has been switched to recording state. </para></listitem><listitem><para> Getting statistics, filtering records: service administrators might want to see the last records related to a given endpoint or operation, the last records related to messages coming from a given customer and the response the system gave them, etc. These information can be obtained using the <emphasis>getRecordsByOperation</emphasis>, <emphasis>getRecordsByClientHost</emphasis> or the more general <emphasis>getMatchingRecords</emphasis> functionality of the MemoryBufferRecorder.</para></listitem></itemizedlist><para> </para></section>
+<section id="JBossWS-Recordsmanagement_How_it_works_and_how_to_use_it"><title>How it works and how to use it</title><para>The recording system is composed of</para><itemizedlist><listitem><para> JAX-WS handlers intercepting inbound and outbound communication </para></listitem><listitem><para> Record processors plugged into deployed endpoints; handlers collect records and send them to every processors through the current endpoint. Processors may store records, convert them, log them, ... </para></listitem><listitem><para> MBean views of processors that can be used to configure and fine tune recording at runtime </para></listitem><listitem><para> Record filters allowing selection of information to be recorded as well as providing means of performing custom queries on the saved records.</para></listitem></itemizedlist><para> </para><section id="JBossWS-Recordsmanagement_Server_side"><title>Server side</title><para>On server side records are collected by JAX-WS handlers and pa!
ssed to the configured processors. JBossWS comes with two default record processors that are plugged into every endpoint during the deployment:</para><itemizedlist><listitem><para> LogRecorder: a simple record processor that writes records to the configured log. </para></listitem><listitem><para> MemoryBufferRecorder: a record processor that keeps the last received records in memory and allows user to search / get statistics on them. </para></listitem></itemizedlist><para>Every processors can be fine tuned to process some record attributes only according to the user and/or performance requirements. Default processors are not in recording mode upon creation, thus you need to switch them to recording mode through their MBean interfaces (see the <emphasis>Recording</emphasis> flag in the jmx-console).</para><para>Common processor properties and their respective defaults values are:</para><itemizedlist><listitem><para> processDestinationHost (true) </para></listitem><listitem><!
para> processSourceHost (true) </para></listitem><listitem><pa!
ra> proc
essHeaders (true) </para></listitem><listitem><para> processEnvelope (true) </para></listitem><listitem><para> processMessageType (true) </para></listitem><listitem><para> processOperation (true) </para></listitem><listitem><para> processDate (true) </para></listitem><listitem><para> recording (false) </para></listitem></itemizedlist><para>The recorders can be configured in the stacks bean configuration</para><screen xml:space="preserve"> <!-- Installed Record Processors-->
+ <bean name="WSMemoryBufferRecorder" class="org.jboss.wsf.framework.management.recording.MemoryBufferRecorder">
+ <property name="recording">false</property>
+ </bean>
+ <bean name="WSLogRecorder" class="org.jboss.wsf.framework.management.recording.LogRecorder">
+ <property name="recording">false</property>
+ </bean>
+</screen><para>The recording system is available for all the JBossWS supported stacks. However slightly different procedure is required to enable it depending on the used stack.</para><variablelist><varlistentry><term><emphasis role="bold">Native stack</emphasis> </term><listitem/></varlistentry></variablelist><para>Native stack comes with <link linkend="chap_JBossWS-JAX-WSEndpointConfiguration">JBossWS - JAX-WS Endpoint Configuration</link>. The default standard endpoint already has the server side recording handler:</para><screen xml:space="preserve"> <endpoint-config>
+ <config-name>Standard Endpoint</config-name>
+ <pre-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>Recording Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.wsf.framework.invocation.RecordingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </pre-handler-chains>
+ </endpoint-config>
+</screen><para>thus nothing is required to use it since it is automatically installed in the pre-handler-chain. Of course you might want to add it to other endpoint configurations you're using.</para><variablelist><varlistentry><term><emphasis role="bold">Metro and CXF stacks </emphasis></term><listitem/></varlistentry></variablelist><para>Other stacks require users to manually add the <emphasis>org.jboss.wsf.framework.invocation.RecordingServerHandler</emphasis> to their endpoint handler chain. This can be done <link linkend="chap_JBossWS-UserGuide">the same way common user handlers are added</link>.</para><para>Once the handler is properly added to the chain, log recording configuration is agnostic to the used stack. Users just need to tune the processors parameters though their MBean interfaces.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Client_side"><title>Client side</title><para>JMX management of processors is of course available on server side only. However users might also be interested in collecting and processing records on client side. Since handlers can be set on client side too, customer handlers could be configured to capture messages almost like the <emphasis>RecordingServerHandler</emphasis> does. This is left to the users since it is directly linked to their custom needs. For instance a common use could be to pass client side collected records to the LogRecorder.</para><para> </para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_Advanced_hints"><title>Advanced hints</title><section id="JBossWS-Recordsmanagement_Adding_custom_recorders"><title>Adding custom recorders</title><para>As previously said, the recording system is extensible: JBossWS users can write their own processors and plug them at runtime into their deployed endpoints through the <emphasis>addRecordProcessor</emphasis> functionality of the ManagedEndpoint MBean. Every processor needs to implement the <emphasis>org.jboss.wsf.spi.management.recording.RecordProcessor</emphasis> interface. Then you can choose one of the two following options:</para><itemizedlist><listitem><para> Give you record processor an MBean interface declaring the manageable attributes: the recording system will plug your processor to the endpoint and register a management MBean for it using your interface. This allows you to create highly configurable custom processors. For an example of this development option, take a look at!
the <emphasis>org.jboss.wsf.framework.management.recording.MemoryBufferRecorder</emphasis>. </para></listitem><listitem><para> Add your record processor to the managed endpoint as is: the recording system will plug it to the endpoint and register a standard management MBean for its basic processing configuration. The <emphasis>org.jboss.wsf.framework.management.recording.LogRecorder</emphasis> is an example of this development option. </para></listitem></itemizedlist><para>A code snippet showing how to get the MBeanProxy instance which you can invoke MBean with can be found <link linkend="chap_JBossWS-Endpointmanagement">here</link>.</para></section>
+<section id="JBossWS-Recordsmanagement_Handlers_position"><title>Handler's position</title><para>Of course the recording handler's position in the handler chain influences the collected records. As a matter of fact some information may or may not be available at a given point of the handler chain execution. The standard endpoint configuration declares the RecordingServerHandler into the pre-handler-chain. Speaking of the native stack, this means for example that you'll get the invoked operation data and that decrypted messages will be recorded if using WS-Security, since the WS-Security handler runs in the post-handler-chain. Users might want to change the recording handler's position in the chain according to their requirements.</para></section>
+<section id="JBossWS-Recordsmanagement_Multiple_handlers"><title>Multiple handlers</title><para>Records attributes include a record group ID that is meant to link records whose messages belong to the same message flow (a request-response for example). In order to set the right group ID to the records, the current ID is associated to the thread that is processing the endpoint invocation. This means that multiple related records can be linked together and extracted together from a processor.</para><para>For this reason, you might want to install multiple recording handlers into different points of the handler chain. For instance, it could make sense to record messages both before and after encryption/decryption when using WS-Security.</para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_Future_extensions"><title>Future extensions</title><para>This paragraph covers eventual future extensions and/or idea JBossWS users may want to leverage for their own business.</para><section id="JBossWS-Recordsmanagement_Database_recorder"><title>Database recorder</title><para>The MemoryBufferRecorder provides interesting functionalities to query the collected records set. For obvious reasons, records are discarded once a given size of the buffer is reached.</para><para>A DB based recorder could be developed; it should work the same way the MemoryBufferRecorder does, except for records that should be saved through a given datasource. This will provide persistence of data even in case of application server reboot and webservice application redeploy. It will also allow records coming from different node of a cluster to be stored together. Finally this would allow administrators to directly query the database, which might be far more eff!
icient.</para></section>
+<section id="JBossWS-Recordsmanagement_Custom_log_writer"><title>Custom log writer</title><para>The idea of getting statistics from collected records could be further exploited getting custom logs from the records. These logs could be outputted by a custom processor in standard or proprietary formats allowing them to be imported into eventual third-party log processing tools which might offer complex/funky graphic or statistic functionalities and so on.</para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_References"><title>References</title><para>You might want to take a look at the <emphasis>org.jboss.wsf.framework.management.recording</emphasis> and <emphasis>org.jboss.wsf.spi.management.recording</emphasis> packages in the source code to better understand how all this works and can be used.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Securetransport.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Securetransport"><title>JBossWS-Securetransport</title><para/><para>JBossWS allows you to require that requests to a given endpoint use SSL by specifying the <emphasis>transportGuarantee</emphasis> attribute in the <ulink url="http://community.jboss.org/docs/DOC-13972#WebContext">@WebContext</ulink> annotation.</para><para>Here is an example using a SLSB endpoint:</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext
+(
+ contextRoot="/my-cxt",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="CONFIDENTIAL",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly to enforce the same requirement on POJO endpoints, you need to edit web.xml and add a user-data-constraint element to your security-constraint element:</para><screen xml:space="preserve"> <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ <user-data-constraint>
+ <transport-guarantee>CONFIDENTIAL</transport-guarantee>
+ </user-data-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role>
+</screen><para>If you're manually creating your service contract, make sure that the endpoint address in your WSDL file uses a secure protocol. The easiest way is to add "<ulink url="https://">https://</ulink>" to the SOAP Address entry:</para><screen xml:space="preserve"> <service name="MyService">
+ <port name="BasicSecuredPort" binding="tns:MyBinding">
+ <soap:address location="<ulink url="https://localhost:8443/my-ctx/SecureEndpoint">https://localhost:8443/my-ctx/SecureEndpoint</ulink>"/>
+ </port>
+ </service>
+</screen><para>For this to work the Tomcat+SSL connector must be enabled:</para><screen xml:space="preserve"> <Connector port="8443" address="${jboss.bind.address}"
+ maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+ scheme="https" secure="true" clientAuth="want"
+ keystoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ keystorePass="jbossws"
+ truststoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ truststorePass="jbossws"
+ sslProtocol = "TLS" />
+</screen><para>Please refer the <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">Tomcat-5.5 SSL Configuration HOWTO</ulink> for further details.</para><para> </para><section id="JBossWS-Securetransport_Client_side"><title>Client side</title><para>On the client side the truststore must be installed:</para><screen xml:space="preserve"> <sysproperty key="javax.net.ssl.keyStore" value="${test.resources.dir}/wsse/wsse.keystore"/>
+ <sysproperty key="javax.net.ssl.trustStore" value="${test.resources.dir}/wsse/wsse.truststore"/>
+ <sysproperty key="javax.net.ssl.keyStorePassword" value="jbossws"/>
+ <sysproperty key="javax.net.ssl.trustStorePassword" value="jbossws"/>
+ <sysproperty key="javax.net.ssl.keyStoreType" value="jks"/>
+ <sysproperty key="javax.net.ssl.trustStoreType" value="jks"/></screen><para>As you can see, this requires you to setup the environment specifying both the location and type of your truststore.</para><para>Finally, in case you see the following exception:</para><screen xml:space="preserve"> java.io.IOException: HTTPS hostname wrong: should be <localhost>
+ at sun.net.www.protocol.https.HttpsClient.checkURLSpoofing(HttpsClient.java:493)
+ at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:418)
+</screen><para>you should disable URL checking on the client side:</para><screen xml:space="preserve"> <sysproperty key="org.jboss.security.ignoreHttpsHost" value="true"/></screen></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-Securityandattachmentssample.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,685 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Securityandattachmentssample"><title>JBossWS-Securityandattachmentssample</title><section id="JBossWS-Securityandattachmentssample_Scenario"><title>Scenario</title><para>This sample targets those web service business scenarios requiring both exchange of attachments and different levels of communication security.</para><para> </para><para>The <emphasis role="bold">org.jboss.test.ws.jaxws.samples.news</emphasis> sample is about an oversimplified newspaper system. News agencies provide press releases to the main newspaper center. Information are processed, articles written and perhaps translated. Once a newspaper edition is ready, printer/distributor centers can download it (as well as previous editions).</para><para>This sample of course focuses on the web service endpoints making the above-mentioned communication possible.</para><para> </para></section>
+<section id="JBossWS-Securityandattachmentssample_Attachments"><title>Attachments</title><para>The JBossWS stack supports two means of using attachment (perhaps binary) to SOAP message: <ulink url="http://community.jboss.org/docs/DOC-13972#MTOMXOP">MTOM/XOP</ulink> and <ulink url="http://http://www.jboss.org/community/wiki/JBossWS-UserGuide#SwaRef">SwaRef</ulink>. Basically both technologies allows attachments to be referenced in SOAP messages, moreover MTOM/XOP provides efficient data serialization for certain content types. Since third-party system might support MTOM/XOP or SwaRef only, we decided here to implement two different endpoints, each of them using one technology.</para><para> </para><section id="JBossWS-Securityandattachmentssample_The_press_release_endpoint"><title>The press release endpoint</title><section id="JBossWS-Securityandattachmentssample_Newspaper_server"><title>Newspaper server</title><para>The press release endpoint implementation is provided in t!
he <emphasis>AbstractPressReleaseEndpoint</emphasis> class and simply outputs the received press release object to the logs:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">abstract</emphasis> <emphasis role="bold">class</emphasis> AbstractPressReleaseEndpoint
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(this.getClass());
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> submitPressRelease(PressRelease release)
+ {
+ log.info("Received a press release from agency: " + release.getAgencyId());
+ log.info("- Title: " + release.getTitle());
+ log.info("- Text: " + release.getBody());
+ }
+}
+</screen><para>Here is the actual web service endpoint implementation:</para><screen xml:space="preserve">@Stateless
+@WebService(name = "PressReleaseEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "PressReleaseService")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/pressRelease")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> PressReleaseEndpoint <emphasis role="bold">extends</emphasis> AbstractPressReleaseEndpoint
+{
+
+}
+</screen><para>To make it really easy, we used a SLSB endpoint without even defining an interface. We chose Document/Literal style/use and explicitely set the service name and namespace, as well as the context root and url pattern through the <emphasis>@WebContext</emphasis> annotation. Thus nothing special here, no attachments stuff required, we're simply preparing a basic service that will be secured in the next chapter.</para><para> </para></section>
+<section id="JBossWS-Securityandattachmentssample_Agency_client"><title>Agency client</title><para>Once the server is implemented, we can deploy it and get the generated wsdl contract. This way we generate the client through the <ulink url="http://community.jboss.org/docs/DOC-13542">wsconsume</ulink> script (assume your bind address is localhost.localdomain:8080):</para><screen xml:space="preserve">wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.news.generated.agency http://localhost.localdomain:8080/news/pressRelease?wsdl
+</screen><para>Referencing the generated classes, we hand code the agency client:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> Agency
+{
+ <emphasis role="bold">protected</emphasis> PressReleaseEndpoint endpoint;
+
+ <emphasis role="bold">public</emphasis> Agency(URL url)
+ {
+ PressReleaseService service = <emphasis role="bold">new</emphasis> PressReleaseService(url, <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/news", "PressReleaseService"));
+ endpoint = service.getPressReleaseEndpointPort();
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> run(String title, String body)
+ {
+ PressRelease pressRelease = <emphasis role="bold">new</emphasis> PressRelease();
+ pressRelease.setAgencyId("agency01");
+ pressRelease.setTitle(title);
+ pressRelease.setBody(body);
+ pressRelease.setDate(<emphasis role="bold">new</emphasis> XMLGregorianCalendarImpl(<emphasis role="bold">new</emphasis> GregorianCalendar()));
+ endpoint.submitPressRelease(pressRelease);
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 3)
+ {
+ Agency agency = <emphasis role="bold">new</emphasis> Agency(<emphasis role="bold">new</emphasis> URL(args[0]));
+ agency.run(args[1], args[2]);
+ System.out.println("Press release sent.");
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Agency client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar org.jboss.test.ws.jaxws.samples.news.Agency http://host:port/news/pressRelease?wsdl title body");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen></section>
+</section>
+<section id="JBossWS-Securityandattachmentssample_The_newspaper_edition_endpoint"><title>The newspaper edition endpoint</title><section id="JBossWS-Securityandattachmentssample_MTOMXOP_newspaper_server"><title>MTOM/XOP newspaper server</title><para>The class used to ship newspaper edition from the main center to the printers/distributors is the following one:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EditionMTOM
+{
+ <emphasis role="bold">private</emphasis> Date date;
+ <emphasis role="bold">private</emphasis> DataHandler content;
+ <emphasis role="bold">private</emphasis> String id;
+
+ <emphasis role="bold">public</emphasis> Date getDate()
+ {
+ <emphasis role="bold">return</emphasis> date;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setDate(Date date)
+ {
+ this.date = date;
+ }
+ @XmlMimeType("text/plain")
+ <emphasis role="bold">public</emphasis> DataHandler getContent()
+ {
+ <emphasis role="bold">return</emphasis> content;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setContent(DataHandler content)
+ {
+ this.content = content;
+ }
+ <emphasis role="bold">public</emphasis> String getId()
+ {
+ <emphasis role="bold">return</emphasis> id;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setId(String id)
+ {
+ this.id = id;
+ }
+}
+</screen><para>Please note the <emphasis>@XmlMimeType</emphasis> annotation used to set the MIME type of the attachment being enclosed to the message. For ease we're using text-plain here, of course a real world use case will almost always require something else, perhaps <emphasis>application/octet-stream</emphasis>.</para><para>The sample newspaper endpoint implementation is quite trivial:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> AbstractNewspaperMTOMEndpoint
+{
+ <emphasis role="bold">private</emphasis> Logger log = Logger.getLogger(this.getClass());
+
+ <emphasis role="bold">public</emphasis> EditionMTOM getNewspaperEdition(String newspaperId)
+ {
+ log.info("Newspaper edition requested: " + newspaperId);
+ EditionMTOM edition = <emphasis role="bold">new</emphasis> EditionMTOM();
+ edition.setContent(<emphasis role="bold">new</emphasis> DataHandler("This is the newspaper document with id " + newspaperId, "text/plain"));
+ edition.setDate(<emphasis role="bold">new</emphasis> Date());
+ edition.setId(newspaperId);
+ <emphasis role="bold">return</emphasis> edition;
+ }
+
+ <emphasis role="bold">public</emphasis> String[] getNewspaperEditionIdList(Date from, Date to)
+ {
+ String[] ids = <emphasis role="bold">new</emphasis> String[2];
+ ids[0] = "doc01";
+ ids[1] = "doc02";
+ <emphasis role="bold">return</emphasis> ids;
+ }
+}
+</screen><para>As you can see the edition's content is provided through the DataHandler class, which allows you to use every content-types you might need. The actual web service configuration is provided through the <emphasis>NewspaperMTOMEndpoint</emphasis>:</para><screen xml:space="preserve">@Stateless
+@WebService(endpointInterface = "org.jboss.test.ws.jaxws.samples.news.NewspaperMTOM",
+ name = "NewspaperMTOMEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperMTOMService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/mtom")
+@BindingType(value = "http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> NewspaperMTOMEndpoint <emphasis role="bold">extends</emphasis> AbstractNewspaperMTOMEndpoint <emphasis role="bold">implements</emphasis> NewspaperMTOM
+{
+
+}
+</screen><para>In this example we're using RPC/Literal to keep things easier; the <emphasis>@BindingType</emphasis> annotation is required to enable MTOM processing.</para><para> </para></section>
+<section id="JBossWS-Securityandattachmentssample_SwaRef_newspaper_server"><title>SwaRef newspaper server</title><para>The class used to ship newspaper edition from the main center to the printers/distributors is the following one:</para><screen xml:space="preserve">@XmlRootElement
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EditionSWA
+{
+ <emphasis role="bold">private</emphasis> Date date;
+ <emphasis role="bold">private</emphasis> DataHandler content;
+ <emphasis role="bold">private</emphasis> String id;
+
+ <emphasis role="bold">public</emphasis> Date getDate()
+ {
+ <emphasis role="bold">return</emphasis> date;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setDate(Date date)
+ {
+ this.date = date;
+ }
+ @XmlElement
+ @XmlAttachmentRef
+ <emphasis role="bold">public</emphasis> DataHandler getContent()
+ {
+ <emphasis role="bold">return</emphasis> content;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setContent(DataHandler content)
+ {
+ this.content = content;
+ }
+ <emphasis role="bold">public</emphasis> String getId()
+ {
+ <emphasis role="bold">return</emphasis> id;
+ }
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setId(String id)
+ {
+ this.id = id;
+ }
+}
+</screen><para>Please note the <emphasis>@XmlAttachmentRef</emphasis> annotation used to define which attribute will be enclosed as attachment. The <emphasis>DataHandler</emphasis> class has to be used here too.</para><para> </para><para>The sample newspaper endpoint implementation is the same as the MTOM one except for the <emphasis>EditionSWA</emphasis> class used instead of <emphasis>EditionMTOM</emphasis>. The web service endpoint configuration instead is simpler, since nothing more than what you would have in an usual endpoint implementation is required:</para><screen xml:space="preserve">@Stateless
+@WebService(endpointInterface = "org.jboss.test.ws.jaxws.samples.news.NewspaperSWA",
+ name = "NewspaperSWAEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperSWAService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/swa")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> NewspaperSWAEndpoint <emphasis role="bold">extends</emphasis> AbstractNewspaperSWAEndpoint <emphasis role="bold">implements</emphasis> NewspaperSWA
+{
+
+}
+</screen></section>
+<section id="JBossWS-Securityandattachmentssample_Printer_client"><title>Printer client</title><para>As for the press release endpoint, we generate the client stuff using the <ulink url="http://community.jboss.org/docs/DOC-13542">wsconsume</ulink> script, given the published wsdl contract:</para><screen xml:space="preserve">wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.news.generated.printer.mtom http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+wsconsume.sh -k -p org.jboss.test.ws.jaxws.samples.news.generated.printer.swa http://localhost.localdomain:8080/news/newspaper/swa?wsdl
+</screen><para>The sample printer is coded referencing the generated classes and allows invocation of both the endpoints:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> Printer
+{
+ <emphasis role="bold">protected</emphasis> NewspaperMTOMEndpoint mtomEndpoint;
+ <emphasis role="bold">protected</emphasis> NewspaperSWAEndpoint swaEndpoint;
+ <emphasis role="bold">protected</emphasis> <emphasis role="bold">boolean</emphasis> mtom;
+
+ <emphasis role="bold">public</emphasis> Printer(URL url, <emphasis role="bold">boolean</emphasis> mtom)
+ {
+ this.mtom = mtom;
+ <emphasis role="bold">if</emphasis> (mtom)
+ {
+ NewspaperMTOMService mtomService = <emphasis role="bold">new</emphasis> NewspaperMTOMService(url, <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/news", "NewspaperMTOMService"));
+ mtomEndpoint = mtomService.getNewspaperMTOMEndpointPort();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ NewspaperSWAService swaService = <emphasis role="bold">new</emphasis> NewspaperSWAService(url, <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/samples/news", "NewspaperSWAService"));
+ swaEndpoint = swaService.getNewspaperSWAEndpointPort();
+ }
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> run() <emphasis role="bold">throws</emphasis> IOException
+ {
+ XMLGregorianCalendar from = <emphasis role="bold">new</emphasis> XMLGregorianCalendarImpl(<emphasis role="bold">new</emphasis> GregorianCalendar(2008,1,10));
+ XMLGregorianCalendar to = <emphasis role="bold">new</emphasis> XMLGregorianCalendarImpl(<emphasis role="bold">new</emphasis> GregorianCalendar(2008,1,14));
+ <emphasis role="bold">if</emphasis> (mtom)
+ {
+ ((SOAPBinding)(((BindingProvider)mtomEndpoint).getBinding())).setMTOMEnabled(<emphasis role="bold">true</emphasis>);
+ <emphasis role="bold">for</emphasis> (String id : mtomEndpoint.getNewspaperEditionIdList(from, to).getItem())
+ {
+ System.out.println("Downloading newspaper document: " + id);
+ EditionMTOM edition = mtomEndpoint.getNewspaperEdition(id);
+ System.out.println("Content: " + edition.getContent());
+ }
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ <emphasis role="bold">for</emphasis> (String id : swaEndpoint.getNewspaperEditionIdList(from, to).getItem())
+ {
+ System.out.println("Downloading newspaper document: " + id);
+ EditionSWA edition = swaEndpoint.getNewspaperEdition(id);
+ DataHandler dh = edition.getContent();
+ System.out.println("Content type: " + dh.getContentType());
+ System.out.println("Content: " + dh.getContent());
+ }
+ }
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ Printer printer = <emphasis role="bold">new</emphasis> Printer(<emphasis role="bold">new</emphasis> URL(args[0]), args[0].endsWith("mtom?wsdl"));
+ printer.run();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("Printer client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar org.jboss.test.ws.jaxws.samples.news.Printer http://host:port/news/newspaper/mtom?wsdl");
+ System.out.println("or");
+ System.out.println("wsrunclient.sh -classpath agency.jar org.jboss.test.ws.jaxws.samples.news.Printer http://host:port/news/newspaper/swa?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>Please note we used the SOAPBinding's <emphasis>setMTOMEnabled(boolean enable)</emphasis> method to enable the MTOM/XOP processing.</para><para> </para></section>
+</section>
+<section id="JBossWS-Securityandattachmentssample_Running_the_sample"><title>Running the sample</title><para>Let's build the sample and take a look at the final contents of the generated archives; the newspaper main center is in <emphasis>jaxws-samples-news-step1-newspaper.jar</emphasis>:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step1-newspaper.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 1867 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperMTOMEndpoint.class
+ 1861 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperSWAEndpoint.class
+ 1281 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractPressReleaseEndpoint.class
+ 1223 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/EditionMTOM.class
+ 1301 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/EditionSWA.class
+ 951 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperMTOM.class
+ 1298 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperMTOMEndpoint.class
+ 948 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperSWA.class
+ 1265 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperSWAEndpoint.class
+ 1208 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/PressRelease.class
+ 1059 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/PressReleaseEndpoint.class
+</screen><para>As you can see, it contains both the press release and newspaper edition endpoint implementations (the latter in MTOM and Swa versions). No descriptor is required.</para><para>The agency archive is <emphasis>jaxws-samples-news-step1-agency.jar</emphasis>:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step1-agency.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 2592 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/Agency.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/
+ 2813 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/ObjectFactory.class
+ 1640 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressRelease.class
+ 865 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseEndpoint.class
+ 1725 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseService.class
+ 1035 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressRelease.class
+ 647 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressReleaseResponse.class
+ 291 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/package-info.class
+</screen><para>It contains nothing more than the hand coded client class and the wsconsume generated classes.</para><para>Finally, the printer archive is <emphasis>jaxws-samples-news-step1-printer.jar</emphasis>:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step1-printer.jar
+ 0 Fri Feb 08 11:40:50 CET 2008 META-INF/
+ 106 Fri Feb 08 11:40:48 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 5444 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/Printer.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/
+ 1599 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/EditionMTOM.class
+ 1115 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMEndpoint.class
+ 1760 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMService.class
+ 958 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/ObjectFactory.class
+ 993 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/StringArray.class
+ 295 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/package-info.class
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/
+ 1717 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/EditionSWA.class
+ 1108 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAEndpoint.class
+ 1746 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAService.class
+ 1896 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/ObjectFactory.class
+ 991 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/StringArray.class
+ 294 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/package-info.class
+</screen><para>The same things just written for the agency archive apply here too.</para><para> </para><para>You need to deploy the newspaper archive to your application server (perhaps you already did so, if you tried creating the client above); then just run the two clients using the <ulink url="http://community.jboss.org/docs/DOC-13529">wsrunclient</ulink> script.</para><para>Running the agency client:</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-news-step1-agency.jar org.jboss.test.ws.jaxws.samples.news.Agency http://localhost.localdomain:8080/news/pressRelease?wsdl Title Body
+</screen><para>you'll get something like this on the server log:</para><screen xml:space="preserve">15:38:30,360 INFO [PressReleaseEndpoint] Received a press release from agency: agency01
+15:38:30,360 INFO [PressReleaseEndpoint] - Title: Title
+15:38:30,360 INFO [PressReleaseEndpoint] - Text: Body
+</screen><para>Running the printer client (MTOM/XOP version):</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-news-step1-printer.jar org.jboss.test.ws.jaxws.samples.news.Printer http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+</screen><para>you'll get this on the client log:</para><screen xml:space="preserve">Downloading newspaper document: doc01
+Content: VGhpcyBpcyB0aGUgbmV3c3BhcGVyIGRvY3VtZW50IHdpdGggaWQgZG9jMDE=
+Downloading newspaper document: doc02
+Content: VGhpcyBpcyB0aGUgbmV3c3BhcGVyIGRvY3VtZW50IHdpdGggaWQgZG9jMDI=
+</screen><para>The capture of one of the exchanged messages shows the <emphasis>xop:Include</emphasis> element being used to reference the attachment:</para><screen xml:space="preserve">HTTP/1.1 200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200801291425)/JBossWeb-2.0
+Content-Type: multipart/related; type="application/xop+xml"; start="<rootpart(a)ws.jboss.org>"; .start-info="text/xml"; .boundary="----=_Part_11_27939361.1202482223654"
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 14:50:23 GMT
+
+------=_Part_11_27939361.1202482223654
+Content-Type: application/xop+xml; type="text/xml"
+Content-Transfer-Encoding: 8bit
+Content-ID: <rootpart(a)ws.jboss.org>
+
+<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header></env:Header><env:Body><ns1:getNewspaperEditionResponse xmlns:ns1='http://org.jboss.ws/samples/news'><return><content><xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:content-454e2c56-10d9-4393-8050-241578a4f812@ws.jboss.org"/></content><date>2008-02-08T15:50:23.652+01:00</date><id>doc02</id></return></ns1:getNewspaperEditionResponse></env:Body></env:Envelope>
+
+------=_Part_11_27939361.1202482223654
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: <content-454e2c56-10d9-4393-8050-241578a4f812(a)ws.jboss.org>
+
+This is the newspaper document with id doc02
+
+------=_Part_11_27939361.1202482223654--
+</screen><para>Finally, running the SwaRef version of printer client:</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-news-step1-printer.jar org.jboss.test.ws.jaxws.samples.news.Printer http://localhost.localdomain:8080/news/newspaper/swa?wsdl
+</screen><para>you'll get this on the client log:</para><screen xml:space="preserve">Downloading newspaper document: doc01
+Content: text/plain
+Content: This is the newspaper document with id doc01
+Downloading newspaper document: doc02
+Content: text/plain
+Content: This is the newspaper document with id doc02
+</screen><para>The capture of one of the exchanged messages shows the MIME attachment being used:</para><screen xml:space="preserve">HTTP/1.1 200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200801291425)/JBossWeb-2.0
+Content-Type: multipart/related; type="text/xml"; start="<rootpart(a)ws.jboss.org>"; .boundary="----=_Part_7_26058.1202481869751"
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 14:44:29 GMT
+
+------=_Part_7_26058.1202481869751
+Content-Type: text/xml; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+Content-ID: <rootpart(a)ws.jboss.org>
+
+<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header></env:Header><env:Body><ns1:getNewspaperEditionResponse xmlns:ns1='http://org.jboss.ws/samples/news'><return><content>cid:0-1202481869750-15993608@ws.jboss.org</content><date>2008-02-08T15:44:29.749+01:00</date><id>doc02</id></return></ns1:getNewspaperEditionResponse></env:Body></env:Envelope>
+
+------=_Part_7_26058.1202481869751
+Content-Type: text/plain
+Content-Transfer-Encoding: binary
+Content-Id: <0-1202481869750-15993608(a)ws.jboss.org>
+
+This is the newspaper document with id doc02
+
+------=_Part_7_26058.1202481869751--</screen></section>
+</section>
+<section id="JBossWS-Securityandattachmentssample_Security"><title>Security</title><para>Securing a web service application implies performing different changes to both consumers and producers to achieve for example confidentiality, accountability, etc. Different degrees of security might be required according to the application's aims. That's the reason why the current sample shows different solutions.</para><para> </para><section id="JBossWS-Securityandattachmentssample_The_press_release_endpoint_305547"><title>The press release endpoint</title><para>Suppose the newspaper and agency's owners want the maximum confidentiality regarding the exchanged press release. Thus we decide to obtain message level security using <link linkend="WSSecurity">WS-Security</link>. In particular, messages will be both encrypted and signed; moreover each of them will have a timestamp.</para><para> </para><para>Assuming the client side to be <emphasis>alice</emphasis> and the server side <emp!
hasis>bob</emphasis>, we're going to use the following jbossws ws-security configuration files (jboss-wsse-client.xml first):</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <key-store-file>META-INF/alice-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+ <trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1" includeTimestamp="true"/>
+ <encrypt type="x509v3" alias="bob"/>
+ <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <key-store-file>META-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+ <trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1" includeTimestamp="true"/>
+ <encrypt type="x509v3" alias="alice"/>
+ <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security></screen><para>Please refer to the <emphasis>src/test/resources/jaxws/samples/news/META-INF/readme.txt</emphasis> file for a contents' explanation of the keystores, truststore and certificates used in the sample.</para><para>The secure web service endpoint is obtained specifying the ws-security endpoint configuration through the <emphasis>@EndpointConfig</emphasis> annotation:</para><screen xml:space="preserve">@Stateless
+@WebService(name = "PressReleaseEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "PressReleaseService")
+@SOAPBinding(style = SOAPBinding.Style.DOCUMENT,
+ use = SOAPBinding.Use.LITERAL)
+@WebContext(contextRoot="/news",
+ urlPattern="/pressRelease")
+@EndpointConfig(configName = "Standard WSSecurity Endpoint")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SecurePressReleaseEndpoint <emphasis role="bold">extends</emphasis> AbstractPressReleaseEndpoint
+{
+
+}
+</screen><para>Of course also the secure agency client needs the right configuration:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SecureAgency <emphasis role="bold">extends</emphasis> Agency
+{
+ <emphasis role="bold">public</emphasis> SecureAgency(URL url)
+ {
+ <emphasis role="bold">super</emphasis>(url);
+ ((StubExt)endpoint).setConfigName("Standard WSSecurity Client");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 3)
+ {
+ Agency agency = <emphasis role="bold">new</emphasis> SecureAgency(<emphasis role="bold">new</emphasis> URL(args[0]));
+ agency.run(args[1], args[2]);
+ System.out.println("Press release sent.");
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("SecureAgency client usage:");
+ System.out.println("./wsrunclient.sh -classpath agency.jar org.jboss.test.ws.jaxws.samples.news.SecureAgency " +
+ "http://localhost.localdomain:8080/news/pressRelease?wsdl title body");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen></section>
+<section id="JBossWS-Securityandattachmentssample_The_newspaper_edition_endpoint_15069"><title>The newspaper edition endpoint</title><para>Suppose the message exchange between the newspaper main center and the printers/distributors has lower security requirements; we decide to achieve accountability through BASIC <ulink url="http://community.jboss.org/docs/DOC-13533">authentication</ulink> and confidentiality <ulink url="http://community.jboss.org/docs/DOC-13534">securing the transport</ulink> with HTTPS.</para><para>The secure MTOM/XOP endpoint implementation is obtained this way:</para><screen xml:space="preserve">@Stateless
+@WebService(endpointInterface = "org.jboss.test.ws.jaxws.samples.news.NewspaperMTOM",
+ name = "NewspaperMTOMEndpoint",
+ targetNamespace = "http://org.jboss.ws/samples/news",
+ serviceName = "NewspaperMTOMService")
+@SOAPBinding(style = SOAPBinding.Style.RPC,
+ use = SOAPBinding.Use.LITERAL)
+@SecurityDomain("JBossWS")
+@WebContext(contextRoot="/news",
+ urlPattern="/newspaper/mtom",
+ authMethod="BASIC",
+ transportGuarantee="CONFIDENTIAL",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+@BindingType(value = "http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SecureNewspaperMTOMEndpoint <emphasis role="bold">extends</emphasis> AbstractNewspaperMTOMEndpoint <emphasis role="bold">implements</emphasis> NewspaperMTOM
+{
+
+}
+</screen><para>For ease, we use the <emphasis>JBossWS</emphasis> default security domain, of course you might want to use another one with your own custom login module. The <emphasis>@WebContext</emphasis> annotation sets the authentication method and enforce the https use (<emphasis>transportGuarantee="CONFIDENTIAL"</emphasis>). The secure SwaRef endpoint implementation is obtained the same way as the MTOM/XOP one.</para><para> </para><para>On the client side, we just need to set the username/password:</para><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SecurePrinter <emphasis role="bold">extends</emphasis> Printer
+{
+ <emphasis role="bold">public</emphasis> SecurePrinter(URL url, <emphasis role="bold">boolean</emphasis> mtom)
+ {
+ <emphasis role="bold">super</emphasis>(url,mtom);
+ BindingProvider bp = mtom ? (BindingProvider)mtomEndpoint : (BindingProvider)swaEndpoint;
+ bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit");
+ bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "thefrog");
+ System.setProperty("org.jboss.security.ignoreHttpsHost", "true");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args)
+ {
+ <emphasis role="bold">try</emphasis>
+ {
+ <emphasis role="bold">if</emphasis> (args.length == 1)
+ {
+ SecurePrinter printer = <emphasis role="bold">new</emphasis> SecurePrinter(<emphasis role="bold">new</emphasis> URL(args[0]), args[0].endsWith("mtom?wsdl"));
+ printer.run();
+ }
+ <emphasis role="bold">else</emphasis>
+ {
+ System.out.println("SecurePrinter client usage:");
+ System.out.println("wsrunclient.sh -classpath agency.jar -Djavax.net.ssl.trustStore=truststorePath -Djavax.net.ssl.trustStorePassword=truststorePwd " +
+ "org.jboss.test.ws.jaxws.samples.news.SecurePrinter http://host:port/news/newspaper/mtom?wsdl");
+ System.out.println("or");
+ System.out.println("wsrunclient.sh -classpath agency.jar -Djavax.net.ssl.trustStore=truststorePath -Djavax.net.ssl.trustStorePassword=truststorePwd " +
+ "org.jboss.test.ws.jaxws.samples.news.SecurePrinter http://host:port/news/newspaper/swa?wsdl");
+ }
+ }
+ <emphasis role="bold">catch</emphasis> (Exception e)
+ {
+ e.printStackTrace();
+ }
+ }
+}
+</screen><para>For an explanation of the reason for setting the <emphasis>org.jboss.security.ignoreHttpsHost</emphasis> property to true, please read <ulink url="http://community.jboss.org/docs/DOC-13534#Client_side">here</ulink>.</para><para>As suggested in the SecurePrinter usage info, you would need to set the <emphasis>javax.net.ssl.trustStore</emphasis> and <emphasis>javax.net.ssl.trustStorePassword</emphasis> for the client to be able to perform the https connection. Finally, we enabled the server Tomcat+SSL connector adding this to the jboss-web.deployer/server.xml:</para><screen xml:space="preserve"><Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
+ maxThreads="150" scheme="https" secure="true"
+ keystoreFile="${jboss.server.home.dir}/my.keystore"
+ truststoreFile="${jboss.server.home.dir}/my.truststore"
+ clientAuth="false" sslProtocol="TLS" /></screen></section>
+<section id="JBossWS-Securityandattachmentssample_Running_the_sample_824473"><title>Running the sample</title><para>Once we build the sample we have the following archives for the secure version:</para><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step2-newspaper.jar
+ 0 Fri Feb 08 17:41:44 CET 2008 META-INF/
+ 106 Fri Feb 08 17:41:42 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 1867 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperMTOMEndpoint.class
+ 1861 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractNewspaperSWAEndpoint.class
+ 1281 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/AbstractPressReleaseEndpoint.class
+ 1223 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/EditionMTOM.class
+ 1301 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/EditionSWA.class
+ 951 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperMTOM.class
+ 948 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/NewspaperSWA.class
+ 1208 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/PressRelease.class
+ 1480 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/SecureNewspaperMTOMEndpoint.class
+ 1379 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/SecureNewspaperSWAEndpoint.class
+ 1173 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/SecurePressReleaseEndpoint.class
+ 2362 Fri Feb 08 11:40:32 CET 2008 META-INF/bob-sign_enc.jks
+ 850 Fri Feb 08 11:40:20 CET 2008 META-INF/jboss-wsse-server.xml
+ 1656 Fri Feb 08 11:40:30 CET 2008 META-INF/wsse10.truststore
+</screen><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step2-agency.jar
+ 0 Fri Feb 08 17:41:44 CET 2008 META-INF/
+ 106 Fri Feb 08 17:41:42 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 2592 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/Agency.class
+ 1461 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/SecureAgency.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/
+ 2813 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/ObjectFactory.class
+ 1640 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressRelease.class
+ 865 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseEndpoint.class
+ 1725 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/PressReleaseService.class
+ 1035 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressRelease.class
+ 647 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/SubmitPressReleaseResponse.class
+ 291 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/agency/package-info.class
+ 2358 Fri Feb 08 11:40:30 CET 2008 META-INF/alice-sign_enc.jks
+ 814 Fri Feb 08 17:41:32 CET 2008 META-INF/jboss-wsse-client.xml
+ 1656 Fri Feb 08 11:40:30 CET 2008 META-INF/wsse10.truststore
+</screen><screen xml:space="preserve">[alessio@localhost trunk]$ jar -tvf output/tests/libs/jaxws-samples-news-step2-printer.jar
+ 0 Fri Feb 08 18:01:14 CET 2008 META-INF/
+ 106 Fri Feb 08 18:01:12 CET 2008 META-INF/MANIFEST.MF
+ 0 Fri Feb 08 11:38:20 CET 2008 org/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/
+ 0 Fri Feb 08 11:38:20 CET 2008 org/jboss/test/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/
+ 5464 Fri Feb 08 17:41:30 CET 2008 org/jboss/test/ws/jaxws/samples/news/Printer.class
+ 2324 Fri Feb 08 18:01:00 CET 2008 org/jboss/test/ws/jaxws/samples/news/SecurePrinter.class
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/
+ 0 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/
+ 1599 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/EditionMTOM.class
+ 1115 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMEndpoint.class
+ 1760 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/NewspaperMTOMService.class
+ 958 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/ObjectFactory.class
+ 993 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/StringArray.class
+ 295 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/mtom/package-info.class
+ 0 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/
+ 1717 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/EditionSWA.class
+ 1108 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAEndpoint.class
+ 1746 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/NewspaperSWAService.class
+ 1896 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/ObjectFactory.class
+ 991 Fri Feb 08 11:39:52 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/StringArray.class
+ 294 Fri Feb 08 11:39:50 CET 2008 org/jboss/test/ws/jaxws/samples/news/generated/printer/swa/package-info.class
+</screen><para>We basically added the secure version of endpoints and clients, as well as the required ws-security descriptors and keystores.</para><para>While running the agency client...</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-news-step2-agency.jar org.jboss.test.ws.jaxws.samples.news.SecureAgency http://localhost.localdomain:8080/news/pressRelease?wsdl title body
+</screen><para>we can for example capture the request message and verify that it's encrypted and signed:</para><screen xml:space="preserve">HTTP/1.1 200 OK
+Server: Apache-Coyote/1.1
+X-Powered-By: Servlet 2.4; JBoss-4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200801291425)/JBossWeb-2.0
+Content-Type: text/xml;charset=UTF-8
+Transfer-Encoding: chunked
+Date: Fri, 08 Feb 2008 19:03:44 GMT
+
+<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'><env:Header><wsse:Security env:mustUnderstand='1' xmlns:wsse='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext...' xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...'><wsu:Timestamp wsu:Id='timestamp'><wsu:Created>2008-02-08T19:03:43.991Z</wsu:Created><wsu:Expires>2008-02-08T19:08:43.991Z</wsu:Expires></wsu:Timestamp><wsse:BinarySecurityToken EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-secu...' ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...' wsu:Id='token-17-1202497424002-6508395'>MIIDDDCCAfSgAwIBAgIQM6YEf7FVYx/tZyEXgVComTANBgkqhkiG9w0BAQUFADAwMQ4wDAYDVQQK
+DAVPQVNJUzEeMBwGA1UEAwwVT0FTSVMgSW50ZXJvcCBUZXN0IENBMB4XDTA1MDMxOTAwMDAwMFoX
+DTE4MDMxOTIzNTk1OVowQjEOMAwGA1UECgwFT0FTSVMxIDAeBgNVBAsMF09BU0lTIEludGVyb3Ag
+VGVzdCBDZXJ0MQ4wDAYDVQQDDAVBbGljZTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAoqi9
+9By1VYo0aHrkKCNT4DkIgPL/SgahbeKdGhrbu3K2XG7arfD9tqIBIKMfrX4Gp90NJa85AV1yiNsE
+yvq+mUnMpNcKnLXLOjkTmMCqDYbbkehJlXPnaWLzve+mW0pJdPxtf3rbD4PS/cBQIvtpjmrDAU8V
+sZKT8DN5Kyz+EZsCAwEAAaOBkzCBkDAJBgNVHRMEAjAAMDMGA1UdHwQsMCowKKImhiRodHRwOi8v
+aW50ZXJvcC5iYnRlc3QubmV0L2NybC9jYS5jcmwwDgYDVR0PAQH/BAQDAgSwMB0GA1UdDgQWBBQK
+4l0TUHZ1QV3V2QtlLNDm+PoxiDAfBgNVHSMEGDAWgBTAnSj8wes1oR3WqqqgHBpNwkkPDzANBgkq
+hkiG9w0BAQUFAAOCAQEABTqpOpvW+6yrLXyUlP2xJbEkohXHI5OWwKWleOb9hlkhWntUalfcFOJA
+gUyH30TTpHldzx1+vK2LPzhoUFKYHE1IyQvokBN2JjFO64BQukCKnZhldLRPxGhfkTdxQgdf5rCK
+/wh3xVsZCNTfuMNmlAM6lOAg8QduDah3WFZpEA0s2nwQaCNQTNMjJC8tav1CBr6+E5FAmwPXP7pJ
+xn9Fw9OXRyqbRA4v2y7YpbGkG2GI9UvOHw6SGvf4FRSthMMO35YbpikGsLix3vAsXWWi4rwfVOYz
+QK0OFPNi9RMCUdSH06m9uLWckiCxjos0FQODZE9l4ATGy9s9hNVwryOJTw==</wsse:BinarySecurityToken><wsse:BinarySecurityToken EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-secu...' ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...' wsu:Id='token-14-1202497424000-24093349'>MIIDCjCCAfKgAwIBAgIQYDju2/6sm77InYfTq65x+DANBgkqhkiG9w0BAQUFADAwMQ4wDAYDVQQK
+DAVPQVNJUzEeMBwGA1UEAwwVT0FTSVMgSW50ZXJvcCBUZXN0IENBMB4XDTA1MDMxOTAwMDAwMFoX
+DTE4MDMxOTIzNTk1OVowQDEOMAwGA1UECgwFT0FTSVMxIDAeBgNVBAsMF09BU0lTIEludGVyb3Ag
+VGVzdCBDZXJ0MQwwCgYDVQQDDANCb2IwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMCquMva
+4lFDrv3fXQnKK8CkSU7HvVZ0USyJtlL/yhmHH/FQXHyYY+fTcSyWYItWJYiTZ99PAbD+6EKBGbdf
+uJNUJCGaTWc5ZDUISqM/SGtacYe/PD/4+g3swNPzTUQAIBLRY1pkr2cm3s5Ch/f+mYVNBR41HnBe
+Ixybw25kkoM7AgMBAAGjgZMwgZAwCQYDVR0TBAIwADAzBgNVHR8ELDAqMCiiJoYkaHR0cDovL2lu
+dGVyb3AuYmJ0ZXN0Lm5ldC9jcmwvY2EuY3JsMA4GA1UdDwEB/wQEAwIEsDAdBgNVHQ4EFgQUXeg5
+5vRyK3ZhAEhEf+YT0z986L0wHwYDVR0jBBgwFoAUwJ0o/MHrNaEd1qqqoBwaTcJJDw8wDQYJKoZI
+hvcNAQEFBQADggEBAIiVGv2lGLhRvmMAHSlY7rKLVkv+zEUtSyg08FBT8z/RepUbtUQShcIqwWse
+mDU8JVtsucQLc+g6GCQXgkCkMiC8qhcLAt3BXzFmLxuCEAQeeFe8IATr4wACmEQE37TEqAuWEIan
+PYIplbxYgwP0OBWBSjcRpKRAxjEzuwObYjbll6vKdFHYIweWhhWPrefquFp7TefTkF4D3rcctTfW
+J76I5NrEVld+7PBnnJNpdDEuGsoaiJrwTW3Ixm40RXvG3fYS4hIAPeTCUk3RkYfUkqlaaLQnUrF2
+hZSgiBNLPe8gGkYORccRIlZCGQDEpcWl1Uf9OHw6fC+3hkqolFd5CVI=</wsse:BinarySecurityToken><xenc:EncryptedKey xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xenc:EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#rsa-1_5' xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/><ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<wsse:SecurityTokenReference wsu:Id='reference-18-1202497424003-32714846'><wsse:Reference URI='#token-17-1202497424002-6508395' ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...'/></wsse:SecurityTokenReference>
+</ds:KeyInfo><xenc:CipherData xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xenc:CipherValue xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'>N6udrhTegMr/BHAWHEFcqASBUYaGUaT4c+j8Ow3PJPcC86comLyTWU1cAjjgmrorKy9TdQ4cqPoI
+/TwKi88yC5E/fDCojmYc1KJV3Jq3jp2j68Z+ZaopLmciiO49ySu7DKsdPL6Cc2bq6bSh6YKgOboH
+8eYfo9OsoAyK8QG4oIc=</xenc:CipherValue></xenc:CipherData><xenc:ReferenceList xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xenc:DataReference URI='#encrypted-16-1202497424001-26591181' xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/></xenc:ReferenceList></xenc:EncryptedKey><ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:SignedInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:CanonicalizationMethod Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:SignatureMethod Algorithm='http://www.w3.org/2000/09/xmldsig#rsa-sha1' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:Reference URI='#element-13-1202497423991-15458568' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transforms xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+</ds:Transforms>
+<ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:DigestValue xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>tfTeWLN1EkJG2rkzORoSvIhOee8=</ds:DigestValue>
+</ds:Reference>
+<ds:Reference URI='#timestamp' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transforms xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<ds:Transform Algorithm='http://www.w3.org/2001/10/xml-exc-c14n#' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+</ds:Transforms>
+<ds:DigestMethod Algorithm='http://www.w3.org/2000/09/xmldsig#sha1' xmlns:ds='http://www.w3.org/2000/09/xmldsig#'/>
+<ds:DigestValue xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>c7QCbyPei07wWMAUaiNSg6lZvZ8=</ds:DigestValue>
+</ds:Reference>
+</ds:SignedInfo>
+<ds:SignatureValue xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+Gib/sFAZQPX1cKtVp3UHbLr275lkOESbRRW/ShX6VVgJRgXaJlqEvzZzbHyzNh8XJdatsP2RJlOs
+A3/By6aejJLPU8bTmb9j2KMUkFid8arvLyF5ezNZc3/YHF+UNjH6JjK1lKwqjE8WF0i4sBFXzUkP
+oGMTkdDaNyLtqYJa+7k=
+</ds:SignatureValue>
+<ds:KeyInfo xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
+<wsse:SecurityTokenReference wsu:Id='reference-15-1202497424000-2041959'><wsse:Reference URI='#token-14-1202497424000-24093349' ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...'/></wsse:SecurityTokenReference>
+</ds:KeyInfo>
+</ds:Signature></wsse:Security></env:Header><env:Body xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...' wsu:Id='element-13-1202497423991-15458568'><xenc:EncryptedData Id='encrypted-16-1202497424001-26591181' Type='http://www.w3.org/2001/04/xmlenc#Content' xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xenc:EncryptionMethod Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc' xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'/>
+<xenc:CipherData xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'><xenc:CipherValue xmlns:xenc='http://www.w3.org/2001/04/xmlenc#'>Wwt17Rt46aEabjJJdir8wTgm+UGkjb4KL5xTlei8GPZHBFfICxdg30HexJHqncjTaGjfx+Z7VFeN
+YxFboMBGjCCln7WqcLZBKUmVffAr/gzMod4OAkMUER2T/GhhQp1hyZH2eo65pgy5slA4dHN5une7
++LuSev4VQRGazsmHOv2ObI4fMUEdD9D/Luvt/WwvmNHd/dyvzBybEZOBuqsZLZA6hzEwWKp6JK0B
+TPiYvRyledLYDtAuZzVTWa70qIOdBlJpTbFmvY3CWZaxXtHWiRTX9I+x88N8hyf/HYbTb3nV+5ZE
+DZgcKjG8fMxF6nGPfcfXr5lm6GqlME4B4ImCPb9AtZqjVKyX3MO166hVLsy0EiqPbiikyWBD07p4
+hbKs1X8n+m9M3SdAVtEeh50zqzpIp96lKlbHmwZ27wro6KQ=
+</xenc:CipherValue>
+</xenc:CipherData>
+</xenc:EncryptedData>
+</env:Body></env:Envelope></screen><para>Instead the MTOM/XOP printer client can be run this way...</para><screen xml:space="preserve">wsrunclient.sh -classpath jaxws-samples-news-step2-printer.jar -Djavax.net.ssl.trustStore=my.truststore -Djavax.net.ssl.trustStorePassword=changeit org.jboss.test.ws.jaxws.samples.news.SecurePrinter http://localhost.localdomain:8080/news/newspaper/mtom?wsdl
+</screen><para>... and of course we can't see the messages' contents due to the SSL encryption.</para></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-UserGuide.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,475 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-UserGuide"><title>JBossWS-UserGuide</title><para/><section id="JBossWS-UserGuide_Introduction_and_architecture"><title>Introduction and architecture</title><para> </para><para>The high level architecture of the JBossWS Web Service Framework is presented in the image here below:</para><para><ulink url="http://jboss.org/file-access/default/members/jbossws/images/wsf.png"><mediaobject><imageobject><imagedata fileref="images/wsf.png" depth="436" width="579"/></imageobject></mediaobject></ulink></para><para> </para><para>This basically means users can choose to download, install and use three different JBossWS versions:</para><itemizedlist><listitem><para><emphasis role="bold">JBossWS Native</emphasis>: this is the JBossWS Web Service Framework integrating the original JBossWS native stack that has been developed in the past years. This is what currently comes installed by default in every JBoss Application Server!
released version and has been used on top of JBoss AS 5 to make it successfully certified for Java EE 5. Please refer the <link linkend="chap_JBossWS-NativeUserGuide">JBossWS Native stack user guide</link> for a complete documentation of JBossWS-Native specific features.</para></listitem><listitem><para><emphasis role="bold">JBossWS CXF</emphasis>: this is the JBossWS Web Service Framework integrating the <ulink url="http://cxf.apache.org/">Apache CXF</ulink> web service stack. Please refer the <ulink url="http://community.jboss.org/docs/DOC-13562">JBossWS CXF stack user guide</ulink> for a complete documentation of JBossWS-CXF specific features.</para></listitem><listitem><para><emphasis role="bold">JBossWS Metro</emphasis>: this is the JBossWS Web Service Framework integrating the <ulink url="https://metro.dev.java.net/">GlassFish Metro</ulink> web service stack. Please refer the <ulink url="http://community.jboss.org/docs/DOC-13561">JBossWS Metro stack user guide</ulink!
> for a complete documentation of JBossWS-Metro specific featu!
res.</pa
ra></listitem></itemizedlist><para> </para><para>The JBossWS web service framework provides common features, tooling, management, deployment framework, etc. for all the supported stacks. At the same time, each stack comes with its own specific functional feature set, performance characteristics and -of course- community. So users can definitely choose the stack that best suits their needs and successfully use it on top of JBoss Application Server.</para><para> </para></section>
+<section id="JBossWS-UserGuide_Common_User_Guide"><title>Common User Guide</title><para> </para><para>Here below is the documentation that applies to every supported stacks. This includes basic JAX-WS usage as well as references to common additional functionalities the JBossWS Web Service Framework provides on top of the supported stacks.</para><section id="JBossWS-UserGuide_Web_Service_Concepts"><title>Web Service Concepts</title><section id="JBossWS-UserGuide_DocumentLiteral"><title>Document/Literal</title><para>With document style web services two business partners agree on the exchange of complex business documents that are well defined in XML schema. For example, one party sends a document describing a purchase order, the other responds (immediately or later) with a document that describes the status of the purchase order. No need to agree on such low level details as operation names and their associated parameters.</para><para>The payload of the SOAP message is an XM!
L document that can be validated against XML schema.</para><para>Document is defined by the style attribute on the SOAP binding.</para><screen xml:space="preserve"> <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
+ <soap:binding style='document' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='concat'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With document style web services the payload of every message is defined by a complex type in XML schema.</para><screen xml:space="preserve"> <complexType name='concatType'>
+ <sequence>
+ <element name='String_1' nillable='true' type='string'/>
+ <element name='long_1' type='long'/>
+ </sequence>
+ </complexType>
+ <element name='concat' type='tns:concatType'/>
+</screen><para>Therefore, message parts <emphasis role="bold">must</emphasis> refer to an <emphasis role="bold">element</emphasis> from the schema.</para><screen xml:space="preserve"> <message name='EndpointInterface_concat'>
+ <part name='parameters' element='tns:concat'/></message>
+</screen><para>The following message definition <emphasis role="bold">is invalid</emphasis>.</para><screen xml:space="preserve"> <message name='EndpointInterface_concat'>
+ <part name='parameters' type='tns:concatType'/></message></screen><section id="JBossWS-UserGuide_DocumentLiteral_Bare"><title>Document/Literal (Bare)</title><para>Bare is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable.</para><para>A bare endpoint or client uses a Java bean that represents the entire document payload.</para><screen xml:space="preserve">@WebService
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DocBareServiceImpl
+{
+ @WebMethod
+ <emphasis role="bold">public</emphasis> SubmitBareResponse submitPO(SubmitBareRequest poRequest)
+ {
+ ...
+ }
+}
+</screen><para>The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.</para><screen xml:space="preserve">@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = "SubmitBareRequest", namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", propOrder = { "product" })
+@XmlRootElement(namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", name = "SubmitPO")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SubmitBareRequest
+{
+ @XmlElement(namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", required = <emphasis role="bold">true</emphasis>)
+ <emphasis role="bold">private</emphasis> String product;
+
+ ...
+}
+</screen></section>
+<section id="JBossWS-UserGuide_DocumentLiteral_Wrapped"><title>Document/Literal (Wrapped)</title><para>Wrapped is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint recognizable.</para><para>A wrapped endpoint or client uses the individual document payload properties. Wrapped is the default and does not have to be declared explicitly.</para><screen xml:space="preserve">@WebService
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DocWrappedServiceImpl
+{
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ <emphasis role="bold">public</emphasis> String submitPO(String product, <emphasis role="bold">int</emphasis> quantity)
+ {
+ ...
+ }
+}
+</screen><para>Note, that with JBossWS the request/response wrapper annotations are <emphasis role="bold">not required</emphasis>, they will be generated on demand using sensible defaults.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_RPCLiteral"><title>RPC/Literal</title><para>With RPC there is a wrapper element that names the endpoint operation. Child elements of the RPC parent are the individual parameters.</para><para>The SOAP body is constructed based on some simple rules:</para><itemizedlist><listitem><para> The port type operation name defines the endpoint method name </para></listitem><listitem><para> Message parts are endpoint method parameters </para></listitem></itemizedlist><para>RPC is defined by the style attribute on the SOAP binding.</para><screen xml:space="preserve"> <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
+ <soap:binding style='rpc' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>' use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>' use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With rpc style web services the portType names the operation (i.e. the java method on the endpoint)</para><screen xml:space="preserve"> <portType name='EndpointInterface'>
+ <operation name='echo' parameterOrder='String_1'>
+ <input message='tns:EndpointInterface_echo'/>
+ <output message='tns:EndpointInterface_echoResponse'/>
+ </operation></portType>
+</screen><para>Operation parameters are defined by individual message parts.</para><screen xml:space="preserve"> <message name='EndpointInterface_echo'>
+ <part name='String_1' type='xsd:string'/></message><message name='EndpointInterface_echoResponse'>
+ <part name='result' type='xsd:string'/></message>
+</screen><para>Note, there is no complex type in XML schema that could validate the entire SOAP message payload.</para><screen xml:space="preserve">@WebService
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> JSEBean01
+{
+ @WebMethod
+ @WebResult(name="result")
+ <emphasis role="bold">public</emphasis> String echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
+}
+</screen><para>The element names of RPC parameters/return values may be defined using the JAX-WS <link linkend="chap_JBossWS-JAX-WSAnnotations">WebParam</link> and <link linkend="chap_JBossWS-JAX-WSAnnotations">WebResult</link> annotations respectively.</para></section>
+<section id="JBossWS-UserGuide_RPCEncoded"><title>RPC/Encoded</title><para>SOAP encodeding style is defined by the infamous <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512">chapter 5</ulink> of the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1</ulink> specification. <emphasis role="bold">It has inherent interoperability issues</emphasis> that cannot be fixed. The <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html">Basic Profile-1.0</ulink> prohibits this encoding style in <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement1...">4.1.7 SOAP encodingStyle Attribute</ulink>.</para><para> JBossWS doesn't support rpc/encoded anymore.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Endpoints"><title>Web Service Endpoints</title><para>JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB.</para><para> </para><section id="JBossWS-UserGuide_Plain_old_Java_Object_POJO"><title>Plain old Java Object (POJO)</title><para>Let's take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations</para><screen xml:space="preserve"> @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> JSEBean01
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ ...
+ }
+ }
+</screen><para><emphasis role="bold">The endpoint as a web application</emphasis></para><para>A JAX-WS java service endpoint (JSE) is deployed as a web application.</para><screen xml:space="preserve"> <web-app ...>
+ <servlet>
+ <servlet-name>TestService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>TestService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+ </web-app>
+</screen><para><emphasis role="bold">Packaging the endpoint</emphasis></para><para>A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file.</para><screen xml:space="preserve"> <war warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war" webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml">
+ <classes dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/>
+ </classes>
+ </war>
+</screen><para>Note, only the endpoint implementation bean and web.xml are required.</para><para><emphasis role="bold">Accessing the generated WSDL</emphasis></para><para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para><screen xml:space="preserve"> http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract off line using jbossw tools. For details of that please see <link linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to WSDL)</link></para><para> </para></section>
+<section id="JBossWS-UserGuide_EJB3_Stateless_Session_Bean_SLSB"><title>EJB3 Stateless Session Bean (SLSB)</title><para>The JAX-WS programming model support the same set of annotations on EJB3 stateless session beans as on <link linkend="JBossWS-UserGuide_Plain_old_Java_Object_POJO">Plain old Java Object (POJO)</link> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC progamming model (with JBossWS-Native only).</para><screen xml:space="preserve"> @Stateless
+ @Remote(EJB3RemoteInterface.class)
+ @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EJB3Bean01 <emphasis role="bold">implements</emphasis> EJB3RemoteInterface
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ ...
+ }
+ }
+</screen><para>Above you see an EJB-3.0 stateless session bean that exposes one method both on the remote interface and on and as an endpoint operation.</para><para><emphasis role="bold">Packaging the endpoint</emphasis></para><para>A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.</para><screen xml:space="preserve"> <jar jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.jar">
+ <fileset dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/>
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/>
+ </fileset>
+ </jar>
+</screen><para><emphasis role="bold">Accessing the generated WSDL</emphasis></para><para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para><screen xml:space="preserve"> http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract off line using jbossw tools. For details of that please see <link linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to WSDL)</link></para><para> </para></section>
+<section id="JBossWS-UserGuide_Endpoint_Provider"><title>Endpoint Provider</title><para>JAX-WS services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations.</para><para>Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.</para><para>A Provider based service instances invoke method is called for each message received for the service.</para><screen xml:space="preserve"> @WebServiceProvider(wsdlLocation = "WEB-INF/wsdl/Provider.wsdl")
+ @ServiceMode(value = Service.Mode.PAYLOAD)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ProviderBeanPayload <emphasis role="bold">implements</emphasis> Provider<Source>
+ {
+ <emphasis role="bold">public</emphasis> Source invoke(Source req)
+ {
+ // Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+ }
+</screen><para>Note, Service.Mode.PAYLOAD is the default and does not have to be declared explicitly. You can also use Service.Mode.MESSAGE to access the entire SOAP message (i.e. with MESSAGE the Provider can also see SOAP Headers)</para><para>The abstract contract for a provider endpoint cannot be derived/generated automatically. Therefore it is necessary to specify the wsdlLocation with the @WebServiceProvider annotation.</para><para> </para></section>
+<section id="JBossWS-UserGuide_WebServiceContext"><title>WebServiceContext</title><para>The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized. The WebServiceContext object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.</para><screen xml:space="preserve"> @WebService
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointJSE
+ {
+ @Resource
+ WebServiceContext wsCtx;
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String testGetMessageContext()
+ {
+ SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
+ <emphasis role="bold">return</emphasis> jaxwsContext != <emphasis role="bold">null</emphasis> ? "pass" : "fail";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String testGetUserPrincipal()
+ {
+ Principal principal = wsCtx.getUserPrincipal();
+ <emphasis role="bold">return</emphasis> principal.getName();
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">boolean</emphasis> testIsUserInRole(String role)
+ {
+ <emphasis role="bold">return</emphasis> wsCtx.isUserInRole(role);
+ }
+ }
+</screen><para> </para><para> </para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Clients"><title>Web Service Clients</title><section id="JBossWS-UserGuide_Service"><title>Service</title><para><computeroutput>Service</computeroutput> is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.</para><para>For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service (see "static case" below).</para><section id="JBossWS-UserGuide_Service_Usage"><title>Service Usage</title><para><emphasis role="bold">Static case</emphasis></para><para>Most clients will start with a WSDL file, and generate some stubs using jbossws tools like <emphasis>wsconsume</emphasis>. This usually gives a mass of files, one of which is the top of the tree. This is!
the service implementation class.</para><para>The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL) and the service name (a javax.xml.namespace.QName) respectively.</para><para>Usually you will use the no-argument constructor. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the WebServiceClient annotation that decorates the generated class.</para><para>The following code snippet shows the generated constructors from the generated class:</para><screen xml:space="preserve">// Generated Service Class
+
+@WebServiceClient(name="StockQuoteService", targetNamespace="<ulink url="http://example.com/stocks">http://example.com/stocks</ulink>", wsdlLocation="<ulink url="http://example.com/stocks.wsdl">http://example.com/stocks.wsdl</ulink>")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> StockQuoteService <emphasis role="bold">extends</emphasis> javax.xml.ws.Service
+{
+ <emphasis role="bold">public</emphasis> StockQuoteService()
+ {
+ <emphasis role="bold">super</emphasis>(<emphasis role="bold">new</emphasis> URL("<ulink url="http://example.com/stocks.wsdl">http://example.com/stocks.wsdl</ulink>"), <emphasis role="bold">new</emphasis> QName("<ulink url="http://example.com/stocks">http://example.com/stocks</ulink>", "StockQuoteService"));
+ }
+
+ <emphasis role="bold">public</emphasis> StockQuoteService(String wsdlLocation, QName serviceName)
+ {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ ...
+}
+</screen><para>Section <link linkend="JBossWS-UserGuide_Dynamic_Proxy">Dynamic Proxy</link> explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at <link linkend="JBossWS-UserGuide_Dispatch">Dispatch</link>.</para><para><emphasis role="bold">Dynamic case</emphasis></para><para>In the dynamic case, when nothing is generated, a web service client uses <computeroutput>Service.create</computeroutput> to create Service instances, the following code illustrates this process.</para><screen xml:space="preserve"> URL wsdlLocation = <emphasis role="bold">new</emphasis> URL("<ulink url="http://example.org/my.wsdl">http://example.org/my.wsdl</ulink>");
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("<ulink url="http://example.org/sample">http://example.org/sample</ulink>", "MyService");
+ Service service = Service.create(wsdlLocation, serviceName);
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-UserGuide_Handler_Resolver"><title>Handler Resolver</title><para>JAX-WS provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a JAX-WS runtime system. <link linkend="JBossWS-UserGuide_Handler_Framework">Handler Framework</link> describes the handler framework in detail. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver methods that may be used to configure a set of handlers on a per-service, per-port or per-protocol binding basis.</para><para>When a Service instance is used to create a proxy or a Dispatch instance then the handler resolver currently registered with the service is used to create the required handler chain. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies, or Dispatch instances.</para></section>
+<section id="JBossWS-UserGuide_Executor"><title>Executor</title><para>Service instances can be configured with a java.util.concurrent.Executor. The executor will then be used to invoke any asynchronous callbacks requested by the application. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service.</para></section>
+</section>
+<section id="JBossWS-UserGuide_Dynamic_Proxy"><title>Dynamic Proxy</title><para>You can create an instance of a client proxy using one of getPort methods on the <link linkend="JBossWS-UserGuide_Service">Service</link>.</para><screen xml:space="preserve"> /**
+ * The getPort method returns a proxy. A service client
+ * uses this proxy to invoke operations on the target
+ * service endpoint. The <code>serviceEndpointInterface</code>
+ * specifies the service endpoint interface that is supported by
+ * the created dynamic proxy instance.
+ **/
+ <emphasis role="bold">public</emphasis> <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+
+ /**
+ * The getPort method returns a proxy. The parameter
+ * <code>serviceEndpointInterface</code> specifies the service
+ * endpoint interface that is supported by the returned proxy.
+ * In the implementation of this method, the JAX-WS
+ * runtime system takes the responsibility of selecting a protocol
+ * binding (and a port) and configuring the proxy accordingly.
+ * The returned proxy should not be reconfigured by the client.
+ *
+ **/
+ <emphasis role="bold">public</emphasis> <T> T getPort(Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+</screen><para>The service endpoint interface (SEI) is usually generated using tools. For details see <link linkend="chap_JBossWS-JAX-WSTools">Top Down (WSDL to Java)</link></para><para>A generated static <ulink url="http://community.jboss.org/Service">Service</ulink> usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.</para><screen xml:space="preserve">@WebServiceClient(name = "TestEndpointService", targetNamespace = "<ulink url="http://org.jboss.ws/wsref">http://org.jboss.ws/wsref</ulink>",
+ wsdlLocation = "<ulink url="http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl">http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl</ulink>")
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> TestEndpointService <emphasis role="bold">extends</emphasis> Service
+{
+ ...
+
+ <emphasis role="bold">public</emphasis> TestEndpointService(URL wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ @WebEndpoint(name = "TestEndpointPort")
+ <emphasis role="bold">public</emphasis> TestEndpoint getTestEndpointPort()
+ {
+ <emphasis role="bold">return</emphasis> (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+}
+</screen><para> </para></section>
+<section id="JBossWS-UserGuide_WebServiceRef"><title>WebServiceRef</title><para>The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250.</para><para>There are two uses to the WebServiceRef annotation:</para><orderedlist><listitem><para> To define a reference whose type is a generated service class. In this case, the type and value element will both refer to the generated service class type. Moreover, if the reference type can be inferred by the field/method declaration the annotation is applied to, the type and value elements MAY have the default value (Object.class, that is). If the type cannot be inferred, then at least the type element MUST be present with a non-default value. </para></listitem><listitem><para> To define a reference whose type is a SEI. In this case, the type element MAY be present with its default value if the type of the reference ca!
n be inferred from the annotated field/method declaration, but the value element MUST always be present and refer to a generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation element, if present, overrides theWSDL location information specified in the WebService annotation of the referenced generated service class. </para></listitem></orderedlist><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EJB3Client <emphasis role="bold">implements</emphasis> EJB3Remote
+{
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpointService service4;
+
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpoint port3;
+</screen><para><emphasis role="bold">WebServiceRef Customization</emphasis></para><para>Starting from jboss-5.0.x we offer a number of overrides and extensions to the WebServiceRef annotation. These include</para><itemizedlist><listitem><para> define the port that should be used to resolve a container-managed port </para></listitem><listitem><para> define default Stub property settings for Stub objects </para></listitem><listitem><para> define the URL of a final WSDL document to be used </para></listitem></itemizedlist><para>Example:</para><screen xml:space="preserve"> <service-ref>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <wsdl-override>file:/wsdlRepository/organization-service.wsdl</wsdl-override>
+ </service-ref>
+
+ <service-ref>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <config-name>Secure Client Config</config-name>
+ <config-file>META-INF/jbossws-client-config.xml</config-file>
+ <handler-chain>META-INF/jbossws-client-handlers.xml</handler-chain>
+ </service-ref>
+
+ <service-ref>
+ <service-ref-name>SecureService</service-ref-name>
+ <service-impl-class>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-impl-class>
+ <service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname>
+ <port-component-ref>
+ <service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface>
+ <port-qname>{http://org.jboss.ws/wsref}SecureEndpointPort</port-qname>
+ <stub-property>
+ <prop-name>javax.xml.ws.security.auth.username</prop-name>
+ <prop-value>kermit</prop-value>
+ </stub-property>
+ <stub-property>
+ <prop-name>javax.xml.ws.security.auth.password</prop-name>
+ <prop-value>thefrog</prop-value>
+ </stub-property>
+ </port-component-ref>
+ </service-ref>
+</screen><para>For details please see <emphasis role="bold">service-ref_5_0.dtd</emphasis> in the jboss docs directory.</para><para> </para></section>
+<section id="JBossWS-UserGuide_Dispatch"><title>Dispatch</title><para>XMLWeb Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.</para><para>Dispatch supports two usage modes, identified by the constants javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:</para><para><emphasis role="bold">Message</emphasis> In this mode, client applications work directly with protocol-specific message structures. E.g., when used with a SOAP protocol binding, a client application would work directly with a SOAP message.</para><para><emphasis role="bold">Message Payload</emphasis> In this mode, client applications work with the payload of messages rather!
than the messages themselves. E.g., when used with a SOAP protocol binding, a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.</para><para>Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Dispatch is a generic class that supports input and output of messages or message payloads of any type.</para><screen xml:space="preserve"> Service service = Service.create(wsdlURL, serviceName);
+ Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD);
+
+ String payload = "<ns1:ping xmlns:ns1='<ulink url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">http://oneway.samples.jaxws.ws.test.jboss.org/'/</ulink>>";
+ dispatch.invokeOneWay(<emphasis role="bold">new</emphasis> StreamSource(<emphasis role="bold">new</emphasis> StringReader(payload)));
+
+ payload = "<ns1:feedback xmlns:ns1='<ulink url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">http://oneway.samples.jaxws.ws.test.jboss.org/'/</ulink>>";
+ Source retObj = (Source)dispatch.invoke(<emphasis role="bold">new</emphasis> StreamSource(<emphasis role="bold">new</emphasis> StringReader(payload)));
+</screen></section>
+<section id="JBossWS-UserGuide_Asynchronous_Invocations"><title>Asynchronous Invocations</title><para>The BindingProvider interface represents a component that provides a protocol binding for use by clients, it is implemented by proxies and is extended by the Dispatch interface.</para><para>BindingProvider instances may provide asynchronous operation capabilities. When used, asynchronous operation invocations are decoupled from the BindingProvider instance at invocation time such that the response context is not updated when the operation completes. Instead a separate response context is made available using the Response interface.</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> testInvokeAsync() <emphasis role="bold">throws</emphasis> Exception
+ {
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL("<ulink url="http://">http://</ulink>" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
+ QName serviceName = <emphasis role="bold">new</emphasis> QName(targetNS, "TestEndpointService");
+ Service service = Service.create(wsdlURL, serviceName);
+ TestEndpoint port = service.getPort(TestEndpoint.class);
+
+ Response response = port.echoAsync("Async");
+
+ // access future
+ String retStr = (String) response.get();
+ assertEquals("Async", retStr);
+ }
+</screen></section>
+<section id="JBossWS-UserGuide_Oneway_Invocations"><title>Oneway Invocations</title><para>@Oneway indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method.</para><screen xml:space="preserve">@WebService (name="PingEndpoint")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> PingEndpointImpl
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> String feedback;
+
+ @WebMethod
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ log.info("ping");
+ feedback = "ok";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String feedback()
+ {
+ log.info("feedback");
+ <emphasis role="bold">return</emphasis> feedback;
+ }
+}
+</screen></section>
+<section id="JBossWS-UserGuide_Oneway_Invocations_703501"><title>Timeout Configuration</title><para>There are two properties to configure the http connection timeout and client receive time out:</para><screen xml:space="preserve"> public void testConfigureTimeout() throws Exception { //Set timeout until a connection is established ((BindingProvider) port).getRequestContext(). put("javax.xml.ws.client.connectionTimeout", "6000"); //Set timeout until the response is received ((BindingProvider) port).getRequestContext(). put("javax.xml.ws.client.receiveTimeout", "1000"); port.echo("testTimeout"); }
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Common_API"><title>Common API</title><para>This sections describes concepts that apply equally to <link linkend="JBossWS-UserGuide_Web_Service_Endpoints">Web Service Endpoints</link> and <link linkend="JBossWS-UserGuide_Web_Service_Clients">Web Service Clients</link>.</para><section id="JBossWS-UserGuide_Handler_Framework"><title>Handler Framework</title><para>The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes. Proxies, and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.</para><para>Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers prior to binding provider processing. Outbound messages are processed by handlers after a!
ny binding provider processing.</para><para>Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Different types of handlers are invoked with different types of message context.</para><section id="JBossWS-UserGuide_Logical_Handler"><title>Logical Handler</title><para>Handlers that only operate on message context properties and message payloads. Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlers are handlers that implement javax.xml.ws.handler.LogicalHandler.</para></section>
+<section id="JBossWS-UserGuide_Protocol_Handler"><title>Protocol Handler</title><para>Handlers that operate on message context properties and protocol specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a message. Protocol handlers are handlers that implement any interface derived from javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler.</para></section>
+<section id="JBossWS-UserGuide_Service_endpoint_handlers"><title>Service endpoint handlers</title><para>On the service endpoint, handlers are defined using the @HandlerChain annotation.</para><screen xml:space="preserve">@WebService
+@HandlerChain(file = "jaxws-server-source-handlers.xml")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SOAPEndpointSourceImpl
+{
+ ...
+}
+</screen><para>The location of the handler chain file supports 2 formats</para><para>1. An absolute java.net.URL in externalForm. (ex: <ulink url="http://myhandlers.foo.com/handlerfile1.xml">http://myhandlers.foo.com/handlerfile1.xml</ulink>)</para><para>2. A relative path from the source file or class file. (ex: bar/handlerfile1.xml)</para></section>
+<section id="JBossWS-UserGuide_Service_client_handlers"><title>Service client handlers</title><para>On the client side, handler can be configured using the @HandlerChain annotation on the SEI or dynamically using the API.</para><screen xml:space="preserve"> Service service = Service.create(wsdlURL, serviceName);
+ Endpoint port = (Endpoint)service.getPort(Endpoint.class);
+
+ BindingProvider bindingProvider = (BindingProvider)port;
+ List<Handler> handlerChain = <emphasis role="bold">new</emphasis> ArrayList<Handler>();
+ handlerChain.add(<emphasis role="bold">new</emphasis> LogHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis> AuthorizationHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis> RoutingHandler());
+ bindingProvider.getBinding().setHandlerChain(handlerChain); // important!
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Message_Context"><title>Message Context</title><para>MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.</para><para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see section 4.2.1) and service endpoint i!
mplementations. The defaultscope for a property is HANDLER.</para><section id="JBossWS-UserGuide_Logical_Message_Context"><title>Logical Message Context</title><para><link linkend="JBossWS-UserGuide_Logical_Handler">Logical Handlers</link> are passed a message context of type LogicalMessageContext when invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of amessage. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para></section>
+<section id="JBossWS-UserGuide_SOAP_Message_Context"><title>SOAP Message Context</title><para>SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.</para></section>
+</section>
+<section id="JBossWS-UserGuide_Fault_Handling"><title>Fault Handling</title><para>An implementation may thow a SOAPFaultException</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> throwSoapFaultException()
+ {
+ SOAPFactory factory = SOAPFactory.newInstance();
+ SOAPFault fault = factory.createFault("this is a fault string!", <emphasis role="bold">new</emphasis> QName("<ulink url="http://foo">http://foo</ulink>", "FooCode"));
+ fault.setFaultActor("mr.actor");
+ fault.addDetail().addChildElement("test");
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> SOAPFaultException(fault);
+ }
+</screen><para>or an application specific user exception</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> throwApplicationException() <emphasis role="bold">throws</emphasis> UserException
+ {
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> UserException("validation", 123, "Some validation error");
+ }
+</screen><note><para><para><emphasis role="bold">Note</emphasis></para><para>In case of the latter JBossWS generates the required fault wrapper beans at runtime if they are not part of the deployment</para><para> </para></para></note>
+</section>
+<section id="JBossWS-UserGuide_JBossWS_Extensions"><title>JBossWS Extensions</title><para>This section describes propriatary JBoss extensions to JAX-WS, that works with all the supported stacks.</para><para> </para><section id="JBossWS-UserGuide_Proprietary_Annotations"><title>Proprietary Annotations</title><para>For the set of standard annotations, please have a look at <link linkend="chap_JBossWS-JAX-WSAnnotations">JAX-WS_Annotations</link>.</para><para> </para><section id="JBossWS-UserGuide_WebContext"><title>WebContext</title><screen xml:space="preserve">/**
+ * Provides web context specific meta data to EJB based web service endpoints.
+ *
+ * @author <ulink url="mailto:thomas.diesler@jboss.org">thomas.diesler(a)jboss.org</ulink>
+ * @since 26-Apr-2005
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> WebContext {
+
+ /**
+ * The contextRoot element specifies the context root that the web service endpoint is deployed to.
+ * If it is not specified it will be derived from the deployment short name.
+ *
+ * Applies to server side port components only.
+ */
+ String contextRoot() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The virtual hosts that the web service endpoint is deployed to.
+ *
+ * Applies to server side port components only.
+ */
+ String[] virtualHosts() <emphasis role="bold">default</emphasis> {};
+
+ /**
+ * Relative path that is appended to the contextRoot to form fully qualified
+ * endpoint address for the web service endpoint.
+ *
+ * Applies to server side port components only.
+ */
+ String urlPattern() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The authMethod is used to configure the authentication mechanism for the web service.
+ * As a prerequisite to gaining access to any web service which are protected by an authorization
+ * constraint, a user must have authenticated using the configured mechanism.
+ *
+ * Legal values for this element are "BASIC", or "CLIENT-CERT".
+ */
+ String authMethod() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The transportGuarantee specifies that the communication
+ * between client and server should be NONE, INTEGRAL, or
+ * CONFIDENTIAL. NONE means that the application does not require any
+ * transport guarantees. A value of INTEGRAL means that the application
+ * requires that the data sent between the client and server be sent in
+ * such a way that it can't be changed in transit. CONFIDENTIAL means
+ * that the application requires that the data be transmitted in a
+ * fashion that prevents other entities from observing the contents of
+ * the transmission. In most cases, the presence of the INTEGRAL or
+ * CONFIDENTIAL flag will indicate that the use of SSL is required.
+ */
+ String transportGuarantee() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * A secure endpoint does not secure wsdl access by default.
+ * Explicitly setting secureWSDLAccess overrides this behaviour.
+ *
+ * Protect access to WSDL. See <ulink url="http://jira.jboss.org/jira/browse/JBWS-723">http://jira.jboss.org/jira/browse/JBWS-723</ulink>
+ */
+ <emphasis role="bold">boolean</emphasis> secureWSDLAccess() <emphasis role="bold">default</emphasis> <emphasis role="bold">false</emphasis>;
+}
+</screen></section>
+<section id="JBossWS-UserGuide_SecurityDomain"><title>SecurityDomain</title><screen xml:space="preserve">/**
+ * Annotation for specifying the JBoss security domain for an EJB
+ *
+ * @author <a href="mailto:<ulink url="mailto:bill@jboss.org">bill(a)jboss.org</ulink>">Bill Burke</a>
+ **/
+(a)Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> SecurityDomain
+{
+ /**
+ * The required name for the security domain.
+ *
+ * Do not use the JNDI name
+ *
+ * Good: "MyDomain"
+ * Bad: "java:/jaas/MyDomain"
+ */
+ String value();
+
+ /**
+ * The name for the unauthenticated pricipal
+ */
+ String unauthenticatedPrincipal() <emphasis role="bold">default</emphasis> "";
+</screen></section></section>
+</section>
+<section id="JBossWS-UserGuide_JAXB_Introductions"><title>JAXB Introductions</title><para>As Kohsuke Kawaguchi writes on <ulink url="http://weblogs.java.net/blog/kohsuke/archive/2007/07/binding_3rd_par.html">his blog</ulink>, one common complaint from the JAXB users is the lack of support for binding 3rd party classes. The scenario is this you are trying to annotate your classes with JAXB annotations to make it XML bindable, but some of the classes are coming from libraries and JDK, and thus you cannot put necessary JAXB annotations on it.</para><para>To solve this JAXB has been designed to provide hooks for programmatic introduction of annotations to the runtime.</para><para>This is currently leveraged by the JBoss JAXB Introductions project, using which users can define annotations in XML and make JAXB see those as if those were in the class files (perhaps coming from 3rd party libraries).</para><para> </para><para>JAXB Introductions are currently supported in JBossWS-N!
ative (server side only, since 3.0.2.GA) and JBossWS-CXF (both server and client side, since 3.2.1.GA).</para><para>Take a look at the <ulink url="http://community.jboss.org/docs/DOC-10075">JAXB Introductions page</ulink> on the wiki and at the examples in the sources.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Tools"><title>Tools</title><para>The JBossWS Web Service Framework provides unified tooling for all the supported stacks. This currently includes common JAX-WS tools for both contract-first and code-first development and common management tools.</para><section id="JBossWS-UserGuide_JAXWS_tools"><title>JAX-WS tools</title><para>Please refer to <link linkend="chap_JBossWS-JAX-WSTools">JBossWS_JAX-WS_Tools</link> for details. This covers directions on web service contract generation (bottom-up development) and consumption (top-down and client development).</para></section>
+<section id="JBossWS-UserGuide_Management_tools"><title>Management tools</title><para>JBoss and its web service framework come with some tools allowing WS endpoint management.</para><para>Please refer the <link linkend="chap_JBossWS-Endpointmanagement">Endpoint management</link> page for an overview of the available tools. In particular the <link linkend="chap_JBossWS-Recordsmanagement">JBossWS - Records management</link> gives administrators a means of performing custom analysis of their web service traffic as well as exporting communication logs.</para></section>
+<section id="JBossWS-UserGuide_Web_Service_console"><title>Web Service console</title><para>All supported stacks provide a web console for getting the list of the endpoints currently deployed on a given host as well as basic metrics regarding invocations to them. The console is available at <ulink url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink> assuming your application server is currently bound to localhost:8080.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Configuration"><title>Configuration</title><section id="JBossWS-UserGuide_Address_rewrite"><title>Address rewrite</title><para>JBossWS allows users to configure the soap:address attribute in the wsdl contract of deployed services as well as wsdl address in the web service console. [due to a known issue this does not currently work with JBossWS-Metro, see: <ulink url="https://jira.jboss.org/jira/browse/JBWS-2462">JBWS-2462</ulink>]</para><para> </para><para><emphasis role="bold">Server configuration options</emphasis></para><para> </para><para>There're few attributes in the jbossws deployers configuration (currently in jbossws.deployer/META-INF/stack-agnostic-jboss-beans.xml) controlling the way the soap:address attribute in the wsdl is rewritten.</para><screen xml:space="preserve"><bean name="WSServerConfig" class="org.jboss.webservices.integration.config.ServerConfigImpl">
+ <property name="mbeanServer"><inject bean="WSMBeanServerLocator" property="mbeanServer"/></property>
+
+ <property name="webServiceHost">${jboss.bind.address}</property>
+ <property name="modifySOAPAddress">true</property>
+
+ <!--
+ <property name="webServiceSecurePort">8443</property>
+ <property name="webServicePort">8080</property>
+ -->
+ </bean>
+</screen><para> </para><para>If the content of <emphasis><soap:address></emphasis> in the wsdl is a valid URL, JBossWS will not rewrite it unless <emphasis>modifySOAPAddress</emphasis> is true. If the content of <emphasis><soap:address></emphasis> is not a valid URL instead, JBossWS will always rewrite it using the attribute values given below. Please note that the variable <emphasis>${jboss.bind.address}</emphasis> can be used to set the address which the application is bound to at each startup.</para><para> </para><para>The webServiceSecurePort and webServicePort attributes are used to explicitly define the ports to be used for rewriting the SOAP address. If these attributes are not set, the ports will be identified by querying the list of installed connectors. If multiple connectors are found the port of the first connector is used.</para><para> </para><para><emphasis role="bold">Dynamic rewrite</emphasis></para><para> </para><para>When the application se!
rver is bound to multiple addresses or non-trivial real-world network architectures cause request for different external addresses to hit the same endpoint, a static rewrite of the soap:address may not be enough. JBossWS allows for both the soap:address in the wsdl and the wsdl address in the console to be rewritten with the host use in the client request. This way, users always get the right wsdl address assuming they're connecting to an instance having the endpoint they're looking for. To trigger this behaviour, the <emphasis role="bold">jbossws.undefined.host</emphasis> value has to be specified for the <emphasis>webServiceHost</emphasis> attribute.</para><screen xml:space="preserve"><property name="webServiceHost">jbossws.undefined.host</property>
+<property name="modifySOAPAddress">true</property></screen><para> </para><para>Of course, when a confidential transport address is required, the addresses are always rewritten using https protocol and the port currently configured for the https/ssl connector.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-WS-Securityoptions.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,200 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-WS-Securityoptions"><title>JBossWS-WS-Securityoptions</title><para>JBossWS implements WS-Security 1.0 specifications to provide users with message level security. The user guide explains <ulink url="http://community.jboss.org/docs/DOC-13532#JBossWS_Native_WS_extensions">how to configure WS-Security</ulink> through declaration files and annotations; for this aim, a simple example shows how to sign (and require signature of) messages.</para><para>This page instead goes deeper into the JBossWS WS-Security configuration details, covering more advanced topics.</para><para/><para> </para><section id="JBossWS-WS-Securityoptions_Username_Token_Authentication"><title>Username Token Authentication</title><para>The following configuration allows clients to authenticate through a Username Token (1). Thanks to the <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=WS-Security_options#JA...">JAAS int!
egration</ulink>, the received token will automatically be verified against the configured JBoss JAAS Security Domain.</para><screen xml:space="preserve"> <jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <config>
+(1) <username/>
+(2) <timestamp ttl="300"/>
+ </config>
+ </jboss-ws-security>
+</screen><para>Line (2) states that a timestamp element must be present in the message and that the message can not be older than 300 seconds; this is used to prevent replay attacks.</para><para>On the server side you should have:</para><screen xml:space="preserve"> <jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <config>
+ <timestamp ttl="300"/>
+ <requires>
+ <username/>
+ </requires>
+ </config>
+ </jboss-ws-security>
+</screen><para>Please note that this way username and password appear as simple text in the SOAP header. Thus it is strongly suggested to use a <link linkend="chap_JBossWS-Securetransport">JBossWS - Secure transport</link>.</para><para> </para><section id="JBossWS-WS-Securityoptions_Password_digest_nonces_and_timestamp"><title>Password digest, nonces and timestamp</title><para>The afore mentioned configuration causes the password to be sent on the wire as a plain text. The Username Token Profile specification allows a digested passwords to be used, even if this doesn't offer real additional security.</para><para>Moreover nonces and creation timestamp can be used as salt to the password digest; this provides some countermeasures to prevent replay attacks.</para><para>To enable password digesting, you basically need to follow these steps:</para><itemizedlist><listitem><para> use the <emphasis>digestPassword</emphasis> attribute in the client wsse configuration (3) </para></l!
istitem><listitem><para> perhaps enable/disable use of nonces (<emphasis>useNonce</emphasis> attribute, default true) and creation timestamp (<emphasis>useCreated</emphasis> attribute, default true) </para></listitem><listitem><para> properly setup the login module of your security domain to use UsernameTokenCallback (4). </para></listitem></itemizedlist><para>Here is an example of the modified client config:</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <config>
+(3) <username digestPassword="true" useNonce="true" useCreated="true"/>
+ <timestamp ttl="300"/>
+ </config>
+</jboss-ws-security>
+</screen><para>And here is a sample login-config.xml showing how to use the UsernameTokenCallback (4):</para><screen xml:space="preserve"><application-policy name="JBossWSDigest">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
+ <module-option name="usersProperties">META-INF/jbossws-users.properties</module-option>
+ <module-option name="rolesProperties">META-INF/jbossws-roles.properties</module-option>
+ <module-option name="hashAlgorithm">SHA</module-option>
+ <module-option name="hashEncoding">BASE64</module-option>
+ <module-option name="hashUserPassword">false</module-option>
+ <module-option name="hashStorePassword">true</module-option>
+ <module-option name="storeDigestCallback">org.jboss.ws.extensions.security.auth.callback.UsernameTokenCallback</module-option>
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</screen><para>Of course you could want to use different login module; the provided <emphasis>UsernameTokenCallback</emphasis> simply adds the nonce and creation timestamp to the digest.</para><para>You can use your custom login module as long as you extend the <emphasis>org.jboss.security.auth.spi.UsernamePasswordLoginModule</emphasis>: then you just need to plug the UsernameTokenCallback into your module and set the hash attributes (<emphasis>hashAlgorithm</emphasis>, <emphasis>hashEncoding</emphasis>, <emphasis>hashUserPassword</emphasis>, <emphasis>hashStorePassword</emphasis>) the way shown above.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Advanced_tuning_nonce_factory"><title>Advanced tuning: nonce factory</title><para>The way nonces are created and checked/stored on server side influences the overall security against replay attacks. In particular currently JBossWS ships with a basic implementation of a nonce store that doesn't cache the received tokens on server side. More complex implementation can be easily plugged in implementing the <emphasis>NonceFactory</emphasis> and <emphasis>NonceStore</emphasis> interfaces you can find in the <emphasis>org.jboss.ws.extensions.security.nonce</emphasis> package. Then you just need to specify you factory class through the <emphasis>nonce-factory-class</emphasis> element in the wsse server config. Future version of JBossWS might come with a nonce store implementation leveraging JBoss Cache or Hibernate to store received nonces.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Advanced_tuning_timestamp_verification"><title>Advanced tuning: timestamp verification</title><para>By default if a Timestamp is present in the wsse:Security header the verification of the header is very strict and does not allow for any tolerance in the time comparisons - if the message appears to have been created even slightly in the future or if the message has just expired then it will be rejected. A new element called 'timestamp-verification' is now available for the wsse configuration. Here is an example of the modified wsse configuration:</para><screen xml:space="preserve"><jboss-ws-security xmlns='<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xsi:schemaLocation='<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>'>
+ <timestamp-verification createdTolerance="5" warnCreated="false" expiresTolerance="10" warnExpires="false" />
+</jboss-ws-security>
+</screen><para>The attributes allow you to specify the tolerance in seconds that is used when verifying the 'Created' or 'Expires' element of the 'Timestamp' header.</para><itemizedlist><listitem><para> <emphasis role="bold">createdTolerance</emphasis> - The number of seconds in the future a message will be accepted. </para></listitem><listitem><para> <emphasis role="bold">expiresTolerance</emphasis> - The number of seconds a message must have been expired for before it will be rejected. </para></listitem></itemizedlist><para>The default value for both of these is 0 which was the orignal behaviour.</para><para>It is also possible to log a warning if a message is accepted due to the configured tolerances that would normally have been rejected, this can then enable you to track down clients where their time is out of synch with the server without rejecting their messages.</para><itemizedlist><listitem><para> <emphasis role="bold">warnCreated</emphasis> - log a warning if a me!
ssage is accepted with a 'Created' value in the future. </para></listitem><listitem><para> <emphasis role="bold">warnExpires</emphasis> - log a warning if a message is accepted with an 'Expires' value in the past. </para></listitem></itemizedlist><para>The default for both of these is true so if you do not require logging you will need to disable these.</para><para><emphasis>Please be aware that the purpose of this tolerance is not to overcome differences relating to different timezones, according to the WSSE specification these times should be UTC - the time and date comparisons used by JBossWS are timezone aware.</emphasis></para><para> </para></section>
+</section>
+<section id="JBossWS-WS-Securityoptions_X509_Certificate_Token"><title>X509 Certificate Token</title><section id="JBossWS-WS-Securityoptions_Encryption"><title>Encryption</title><para>Using X509v3 certificates you can both sign and encrypt messages.</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+(1) <key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+ <trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+
+ <config>
+ <timestamp ttl="300"/>
+(2) <sign type="x509v3" alias="1" includeTimestamp="true"/>
+(3) <encrypt type="x509v3"
+ alias="alice"
+ algorithm="aes-256"
+ keyWrapAlgorithm="rsa_oaep"
+ tokenReference="keyIdentifier" />
+(4) <requires>
+ <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security>
+</screen><para>The server configuration shown above includes:</para><orderedlist><listitem><para> Keystore and truststore information: location, password and type. </para></listitem><listitem><para> Signature configuration: you need to provide the certificate/key pair alias to use. <emphasis>includeTimestamp</emphasis> specifies whether the timestamp is to be signed too to prevent tampering. </para></listitem><listitem><para> Encryption configuration: you need to provide the certificate/key pair alias to use. </para></listitem><listitem><para> Optional security requirements: incoming messages should be both signed and encrypted. </para></listitem></orderedlist><para>Client side configuration works the same way.</para><para> </para><section id="JBossWS-WS-Securityoptions_Algorithms"><title>Algorithms</title><para>Asymmetric + symmetric encryption is performed whenever the <emphasis>encrypt</emphasis> element is found. Thus message data are encrypted using a generated symm!
etric secret key. This is written in the SOAP header after being encrypted (wrapped) with the receiver public key. You can set both the encryption and key wrap algorithms.</para><variablelist><varlistentry><term>Supported encryption algorithms </term><listitem/></varlistentry></variablelist><para> </para><itemizedlist><listitem><para> AES 128 (aes-128) (<emphasis>default</emphasis>) </para></listitem><listitem><para> AES 192 (aes-192) </para></listitem><listitem><para> AES 256 (aes-256) </para></listitem><listitem><para> Triple DES (triple-des) </para></listitem></itemizedlist><variablelist><varlistentry><term>Supported key wrap algorithms </term><listitem/></varlistentry></variablelist><para> </para><itemizedlist><listitem><para> RSA v.1.5 (rsa_15) (<emphasis>default</emphasis>) </para></listitem><listitem><para> RSA OAEP (rsa_oaep) </para></listitem></itemizedlist><para>The <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">Unlimited Strength Java(TM) Cryp!
tography Extension</ulink> installation might be required to r!
un some
strong algorithms (like AES-256). Please note that your country might have limits on allowed crypto strength.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Dynamic_encryption"><title>Dynamic encryption</title><para>When replying to multiple clients, a service provider has to encrypt a message using the right public key according to its destination. The JBossWS native implementation of WS-Security gets the right key to use from the signature received (and verified) in the incoming message. You just need to require signature (1) and do not specify any encryption alias on server side (2):</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <key-store-file>WEB-INF/bob-sign_enc.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+ <trust-store-file>WEB-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+
+ <config>
+ <timestamp ttl="300"/>
+ <sign type="x509v3" alias="1" includeTimestamp="true"/>
+(2) <encrypt type="x509v3"
+ algorithm="aes-256"
+ keyWrapAlgorithm="rsa_oaep"
+ tokenReference="keyIdentifier" />
+ <requires>
+(1) <signature/>
+ <encryption/>
+ </requires>
+ </config>
+</jboss-ws-security>
+</screen><para>Of course you'll have to add every new client's public key to the server side keystore, but no change to the descriptors and service implementation is required.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Token_references"><title>Token references</title><para>For interoperability reason you might want to configure the type of reference to encryption token to be used. For instance, Microsoft Indigo doesn't support direct reference to local binary security tokens that is the JBossWS default reference type choice. Allowed values for <emphasis>tokenReference</emphasis> attribute are:</para><itemizedlist><listitem><para> directReference (<emphasis>default</emphasis>) </para></listitem><listitem><para> keyIdentifier </para></listitem><listitem><para> x509IssuerSerial </para></listitem></itemizedlist><para>Please refer to the <ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profil...">X.509 Token Profile 1.0</ulink> specification for further details on token references.</para><para> </para></section>
+</section>
+<section id="JBossWS-WS-Securityoptions_Targets_configuration"><title>Targets configuration</title><para>JBossWS gives you a fine grained control over the elements that have to be signed or encrypted.</para><para>This allows you to encrypt important data only (like credit card numbers) without waisting time on other information exchanged by the same service (email addresses, for example). To configure this, you just need to specify the QName of the SOAP elements to encrypt. The default behavior is to encrypt the whole SOAP body.</para><screen xml:space="preserve"><encrypt type="x509v3" alias="alice">
+ <targets>
+ <target type="qname">{http://www.my-company.com/cc}CardNumber</target>
+ <target type="qname">{http://www.my-company.com/cc}CardExpiration</target>
+ <target type="qname" contentOnly="true">{http://www.my-company.com/cc}CustomerData</target>
+ </targets>
+</encrypt>
+</screen><para>The <emphasis>contentOnly</emphasis> attribute states whether the content of the element is to be encrypted as opposed to the entire element (default behavior). Target can be specified also for requirements upon message receipt.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Miscellanea"><title>Miscellanea</title><section id="JBossWS-WS-Securityoptions_Signature_and_carriage_returns"><title>Signature and carriage returns</title><para>Exchanging signed messages whose payload contains carriage returns can lead to signature verification errors. That's because of the way the <emphasis>\r</emphasis> special character is handled by xml parsers. To prevent this kind of issue, besides custom encoding the payload before sending it, users can either also encrypt the message or force JBossWS to perform canonical normalization of messages. This can be triggered setting the <emphasis>org.jboss.ws.DOMContentCanonicalNormalization</emphasis> property to true in the MessageContext just before the invocation on client side and in the endpoint implementation. Please note there's a convenient constant for this in <emphasis>org.jboss.ws.Constants</emphasis>; also see the <emphasis>org.jboss.test.ws.jaxws.jbws2011.CRLFTestCas!
e</emphasis> for an example.</para><para> </para></section>
+</section>
+</section>
+<section id="JBossWS-WS-Securityoptions_JAAS_integration"><title>JAAS integration</title><para>The WS-Security implementation allows users to achieve J2EE declarative security through JAAS integration. The calling user's identity and credential are derived from the wsse headers of the incoming message according to the parameters provided in the server wsse configuration file. Authentication and authorization are then achieved delegating to the JAAS login modules configured for the specified security domain.</para><para> </para><section id="JBossWS-WS-Securityoptions_Username_token"><title>Username token</title><para>Username Token Profile provides a mean of specifying the caller's username and password. The wsse server configuration file can be used to have those information used when performing authentication and authorization through configured login module.</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/confi!
g">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <config>
+ <username/>
+ <authenticate>
+ <usernameAuth/>
+ </authenticate>
+ </config>
+</jboss-ws-security>
+</screen><para>Prior to JBossWs 3.0.2 Native the username token was always used to set principal and credential of the caller whenever specified. This means that for backward compatibility reasons, this behavior is obtained also when no <emphasis>authenticate</emphasis> tag at all is specified and the username token is used.</para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_X509_certificate_token"><title>X.509 certificate token</title><para>Whenever a WS-Security message containing X.509 certificates is received, every certificate is validated against the truststore specified in the wsse configuration file. After this validation process, one of the X.509 certificate token can be chosen to extract the caller's principal and perform authentication and authorization using it as credential.</para><para>The current implementation allows the certificate token referenced by the signature token to be used for this purpose (1):</para><screen xml:space="preserve"><jboss-ws-security xmlns="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://www.jboss.com/ws-security/config">http://www.jboss.com/ws-security/config</ulink>
+ <ulink url="http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd">http://www.jboss.com/ws-security/schema/jboss-ws-security_1_0.xsd</ulink>">
+ <key-store-file>META-INF/bob-sign.jks</key-store-file>
+ <key-store-password>password</key-store-password>
+ <key-store-type>jks</key-store-type>
+ <trust-store-file>META-INF/wsse10.truststore</trust-store-file>
+ <trust-store-password>password</trust-store-password>
+ <config>
+ <sign type="x509v3" alias="1" includeTimestamp="false"/>
+ <requires>
+ <signature/>
+ </requires>
+ <authenticate>
+(1) <signatureCertAuth certificatePrincipal="org.jboss.security.auth.certs.SubjectCNMapping"/>
+ </authenticate>
+ </config>
+</jboss-ws-security>
+</screen><para>The optional <emphasis>certificatePrincipal</emphasis> attributes specifies the class to be used to get the principal from the X509 certificate's attributes; it has to implement <ulink url="http://wiki.jboss.org/wiki/CertificatePrincipal">CertificatePrincipal</ulink> and the default one used when no attribute is specified is <emphasis>org.jboss.security.auth.certs.SubjectDNMapping</emphasis>.</para><para>The configured security domain needs at least a <ulink url="http://wiki.jboss.org/wiki/BaseCertLoginModule">BaseCertLoginModule</ulink> to be set up. Here is an example of a security domain with a CertRolesLoginModule, which also enables authorization (using the specified jbossws-roles.properties file):</para><screen xml:space="preserve"><application-policy name="JBossWSCert">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.CertRolesLoginModule" flag="required">
+ <module-option name="rolesProperties">jbossws-roles.properties</module-option>
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ <module-option name="securityDomain">java:/jaas/JBossWSCert</module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</screen><para>Finally, the BaseCertLoginModule of course uses a central keystore to perform user validation. This store is configured through the <emphasis>org.jboss.security.plugins.JaasSecurityDomain</emphasis> MBean as shown in the following jboss-service.xml configuration fragment:</para><screen xml:space="preserve"><mbean code="org.jboss.security.plugins.JaasSecurityDomain"
+ name="jboss.security:service=SecurityDomain">
+ <constructor>
+ <arg type="java.lang.String" value="JBossWSCert"/>
+ </constructor>
+ <attribute name="KeyStoreURL">resource:META-INF/keystore.jks</attribute>
+ <attribute name="KeyStorePass">password</attribute>
+ <depends>jboss.security:service=JaasSecurityManager</depends>
+</mbean>
+</screen><para>The JBoss security code will access the keystore with the principal that JBossWS got from the wsse header using the specified CertificatePrincipal mapping class. If a certificate is found and is the same of the one specified in the wsse header, the user is logged in.</para><para>For a working sample of X509 certificate authentication you may want to take a look at the <emphasis>org.jboss.test.ws.jaxws.jbws2116.CertAuthTestCase</emphasis>.</para><para> </para></section>
+</section>
+<section id="JBossWS-WS-Securityoptions_POJO_Endpoint__Authentication_and_Authorization"><title>POJO Endpoint - Authentication and Authorization</title><para>In general the credentials obtained by WS-Security are only used for EJB endpoints or for POJO endpoints when they make a call to another secured resource, it is now possible to enable authentication and authorization checking for POJO endpoints. (This should not be enabled for EJB based endpoints as the EJB container will still take care of the security requirements of the deployed bean).</para><para><emphasis>These instructions assume WS-Security has already been enabled, these instructions describe the additional configuration required to enable authentication and authorization for POJO endpoints</emphasis></para><para>The first stage is that the war containing the POJO endpoint needs to have a security domain defined, this is achieved by defining a <security-domain> in the jboss-web deployment descriptor with!
in the WEB-INF folder.</para><screen xml:space="preserve"><jboss-web>
+ <security-domain>java:/jaas/JBossWS</security-domain>
+</jboss-web>
+</screen><para>The remainder of the configuration to enable authentication and authorization is within the jboss-wsse-server.xml deployment descriptor.</para><para>To enable the POJO authentication and authorization first a new <authorization> element needs to be added to the appropriate <config> element within the descriptor: -</para><screen xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <!-- Must contain either <unchecked/> or one or more <role>RoleName</role> definitions. -->
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>The config element can be defined globally, be port specific or even be operation specific.</para><para>The authorize element must contain either the <unchecked/> element or one or more <role>RoleName</role> elements.</para><screen xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <unchecked/>
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>This first example had <unchecked/> defined, this means that the authentication step will be performed to validate the users username and credential but no further role checking will take place. If the users username and credential are invalid then the request will be rejected otherwise the request will be allowed to proceed.</para><screen xml:space="preserve"><jboss-ws-security>
+
+ <config>
+ <authorize>
+ <role>friend</role>
+ <role>family</role>
+ </authorize>
+ </config>
+
+</jboss-ws-security>
+</screen><para>This second example has two roles defined, as before the user will be authenticated using their username and credential and they will then be checked to ensure that they have been assigned at least one of the roles 'friend' or 'family'.</para><para><emphasis>It should be noted that the authentication and authorization still proceeds even if no username and password or certificate was provided in the request message, in this scenario authentication may proceed if the login module of the security domain has been configured with an anonymous identity.</emphasis></para><para> </para></section>
+<section id="JBossWS-WS-Securityoptions_Further_information"><title>Further information</title><itemizedlist><listitem><para> The complete wsse configuration is specified in the <emphasis>src/main/resources/schema/jboss-ws-security_1_0.xsd</emphasis> schema that is available in the source code base. </para></listitem><listitem><para> The advanced examples described above are covered by the interoperability scenarios available in the <emphasis>org.jboss.test.ws.interop</emphasis> package. </para></listitem><listitem><para> If you have doubts on the keystore/truststore content requirements for signing/encrypting messages, <link linkend="chap_index">read here</link>. Moreover you can find a text file in the sources showing the store configuration used for the interoperability tests (<emphasis>src/test/resources/interop/nov2007/wsse/shared/META-INF/readme.txt</emphasis>). </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsconsume.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsconsume"><title>JBossWS-wsconsume</title><para>wsconsume is a command line tool and ant task that "consumes" the abstract contract (WSDL file) and produces portable JAX-WS service and client artifacts. For a more detailed overview, see <ulink url="http://community.jboss.org/docs/DOC-13544#TopDown_Using_wsconsume">"Using wsconsume"</ulink>.</para><para/><section id="JBossWS-wsconsume_Command_Line_Tool"><title>Command Line Tool</title><para>The command line tool has the following usage:</para><screen xml:space="preserve">usage: wsconsume [options] <wsdl-url>
+options:
+ -h, --help Show this help message
+ -b, --binding=<file> One or more JAX-WS or JAXB binding files
+ -k, --keep Keep/Generate Java source
+ -c --catalog=<file> Oasis XML Catalog file for entity resolution
+ -p --package=<name> The target package for generated source
+ -w --wsdlLocation=<loc> Value to use for @WebServiceClient.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -t, --target=<2.0|2.1|2.2> The JAX-WS specification target
+ -q, --quiet Be somewhat more quiet
+ -v, --verbose Show full exception stack traces
+ -l, --load-consumer Load the consumer and exit (debug utility)
+ -e, --extension Enable SOAP 1.2 binding extension
+ -a, --additionalHeaders Enables processing of implicit SOAP headers</screen><para> </para><para><emphasis role="bold">Note</emphasis> : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.</para><section id="JBossWS-wsconsume_Examples"><title>Examples</title><para>Generate artifacts in Java class form only:</para><screen xml:space="preserve">wsconsume Example.wsdl
+</screen><para>Generate source and class files:</para><screen xml:space="preserve">wsconsume -k Example.wsdl
+</screen><para>Generate source and class files in a custom directory:</para><screen xml:space="preserve">wsconsume -k -o custom Example.wsdl
+</screen><para>Generate source and class files in the org.foo package:</para><screen xml:space="preserve">wsconsume -k -p org.foo Example.wsdl
+</screen><para>Generate source and class files using multiple binding files:</para><screen xml:space="preserve">wsconsume -k -b wsdl-binding.xml -b schema1-binding.xml -b schema2-binding.xml</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Maven_Plugin"><title>Maven Plugin</title><para>The wsconsume tools is included in the <emphasis role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis>wsconsume</emphasis> and <emphasis>wsconsume-test</emphasis>, which basically do the same during different maven build phases (the former triggers the sources generation during <emphasis>generate-sources</emphasis> phase, the latter during the <emphasis>generate-test-sources</emphasis> one).</para><para>The wsconsume plugin has the following parameters:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default </entry></row></thead><tbody><row><entry>bindingFiles</entry><entry>JAXWS or JAXB binding file</entry><entry>true</entry></row><row><entry>classpath!
Elements</entry><entry><para>Each classpathElement provides a</para><para>library file to be added to classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>catalog</entry><entry>Oasis XML Catalog file for entity resolution</entry><entry>none</entry></row><row><entry>targetPackage</entry><entry>The target Java package for generated code.</entry><entry>generated</entry></row><row><entry>bindingFiles</entry><entry>One or more JAX-WS or JAXB binding file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value to use for @WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>outputDirectory</entry><entry>The output directory for generated artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>sourceDirectory</entry><entry!
>The output directory for Java source.</entry><entry>${project!
.build.d
irectory}/wsconsume/java</entry></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</entry><entry>false</entry></row><row><entry>wsdls</entry><entry>The WSDL files or URLs to consume</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsconsume_Examples_873412"><title>Examples</title><para>You can use wsconsume in your own project build simply referencing the <emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in your pom.xml file.</para><para>The following example makes the plugin consume the test.wsdl file and generate SEI and wrappers' java sources. The generated sources are then compiled together with the other project classes.</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>You can also specify multiple wsdl files, as well as force the target package, enable SOAP 1.2 binding and turn the tool's verbose mode on:</para><para> </para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ <wsdl>${basedir}/test2.wsdl</wsdl>
+ </wsdls>
+ <targetPackage>foo.bar</targetPackage>
+ <extension>true</extension>
+ <verbose>true</verbose>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>Finally, if the wsconsume invocation is required for consuming a wsdl to be used in your testsuite only, you might want to use the <emphasis>wsconsume-test</emphasis> goal as follows:</para><para> </para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Ant_Task"><title>Ant Task</title><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSConsumeTask. Also put streamBuffer.jar and stax-ex.jar in the classpath of the ant task to generate the appropriate artefacts. Both jar files are in the jbossws lib directory. For jbossws-native-2.0.3.GA these files are not automatically installed if you run jboss-deployXX.</emphasis></para></para></note><para>The wsconsume ant task has the following attributes:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default </entry></row></thead><tbody><row><entry>fork</entry><entry>Whether or not to run the generation task in a separate VM.</entry><entry>true</entry></row><row><entry>keep</e!
ntry><entry>Keep/Enable Java source code generation.</entry><entry>false</entry></row><row><entry>catalog</entry><entry>Oasis XML Catalog file for entity resolution</entry><entry>none</entry></row><row><entry>package</entry><entry>The target Java package for generated code.</entry><entry>generated</entry></row><row><entry>binding</entry><entry>A JAX-WS or JAXB binding file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value to use for @WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>destdir</entry><entry>The output directory for generated artifacts.</entry><entry>"output"</entry></row><row><entry>sourcedestdir</entry><entry>The output directory for Java source.</entry><entry>value of destdir</entry></row><row><entry>target</entry><entry>The JAX-WS specification target. Allowed values are 2.0, 2.1 and 2.2</entry><entry/></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</en!
try><entry>false</entry></row><row><entry>wsdl</entry><entry>T!
he WSDL
file or URL</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry><para>false</para></entry></row><row><entry>additionalHeaders</entry><entry>Enables processing of implicit SOAP headers</entry><entry>false</entry></row></tbody></tgroup></informaltable><para><emphasis role="bold">Note</emphasis> : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.</para><para> </para><para>Also, the following nested elements are supported:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Element</entry><entry>Des!
cription</entry><entry>Default </entry></row></thead><tbody><row><entry>binding</entry><entry>A JAXWS or JAXB binding file</entry><entry>none</entry></row><row><entry>jvmarg</entry><entry>Allows setting of custom jvm arguments</entry><entry/></row></tbody></tgroup></informaltable><para> </para><section id="JBossWS-wsconsume_Examples_49471"><title>Examples</title><para>Generate JAX-WS source and classes in a separate JVM with separate directories, a custom wsdl location attribute, and a list of binding files from foo.wsdl:</para><screen xml:space="preserve"><wsconsume
+ fork="true"
+ verbose="true"
+ destdir="output"
+ sourcedestdir="gen-src"
+ keep="true"
+ wsdllocation="handEdited.wsdl"
+ wsdl="foo.wsdl">
+ <binding dir="binding-files" includes="*.xml" excludes="bad.xml"/>
+</wsconsume></screen></section>
+</section>
+<section id="JBossWS-wsconsume_Related_information"><title>Related information</title><itemizedlist><listitem><para> <ulink url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html">JAX-WS binding customization</ulink> </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsprovide.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsprovide"><title>JBossWS-wsprovide</title><para>wsprovide is a command line tool and ant task that generates portable JAX-WS artifacts for a service endpoint implementation. It also has the option to "provide" the abstract contract for offline usage. See <ulink url="http://community.jboss.org/docs/DOC-13544#BottomUp_Using_wsprovide">"Using wsprovide"</ulink> for a detailed walk-through.</para><para/><section id="JBossWS-wsprovide_Command_Line_Tool"><title>Command Line Tool</title><para>The command line tool has the following usage:</para><screen xml:space="preserve"> usage: wsprovide [options] <endpoint class name>
+ options:
+ -h, --help Show this help message
+ -k, --keep Keep/Generate Java source
+ -w, --wsdl Enable WSDL file generation
+ -c. --classpath=<path< The classpath that contains the endpoint
+ -o, --output=<directory> The directory to put generated artifacts
+ -r, --resource=<directory> The directory to put resource artifacts
+ -s, --source=<directory> The directory to put Java source
+ -e, --extension Enable SOAP 1.2 binding extension
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces</screen><section id="JBossWS-wsprovide_Examples"><title>Examples</title><para>Generating wrapper classes for portable artifacts in the "generated" directory:</para><screen xml:space="preserve">wsprovide -o generated foo.Endpoint
+</screen><para>Generating wrapper classes and WSDL in the "generated" directory</para><screen xml:space="preserve">wsprovide -o generated -w foo.Endpoint
+</screen><para>Using an endpoint that references other jars</para><screen xml:space="preserve">wsprovide -o generated -c application1.jar:application2.jar foo.Endpoint</screen></section>
+</section>
+<section id="JBossWS-wsprovide_Maven_Plugin"><title>Maven Plugin</title><para>The wsprovide tools is included in the <emphasis role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis>wsprovide</emphasis> and <emphasis>wsprovide-test</emphasis>, which basically do the same during different maven build phases (the former triggers the sources generation during <emphasis>process-classes</emphasis> phase, the latter during the <emphasis>process-test-classes</emphasis> one).</para><para>The wsprovide plugin has the following parameters:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry> Attribute </entry><entry> Description </entry><entry> Default </entry></row></thead><tbody><row><entry>testClasspathElements</entry><entry><para>Each classpathElement provides a</para><para>library file to b!
e added to classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>outputDirectory</entry><entry>The output directory for generated artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>resourceDirectory</entry><entry>The output directory for resource artifacts (WSDL/XSD).</entry><entry>${project.build.directory}/wsprovide/resources</entry></row><row><entry>sourceDirectory</entry><entry>The output directory for Java source.</entry><entry>${project.build.directory}/wsprovide/java</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row><row><entry>generateWsdl</entry><entry>Whether or not to generate WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables more informational output!
about command progress.</entry><entry>false</entry></row><row!
><entry>
<emphasis role="bold">endpointClass</emphasis></entry><entry><emphasis role="bold">Service Endpoint Implementation.</emphasis></entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsprovide_Examples_309492"><title>Examples</title><para>You can use wsprovide in your own project build simply referencing the <emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in your pom.xml file.</para><para>The following example makes the plugin provide the wsdl file and artifact sources for the specified endpoint class:</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>@pom.version(a)</version>
+ <configuration>
+ <verbose>true</verbose>
+ <endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>The following example does the same, but is meant for use in your own testsuite:</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>@pom.version(a)</version>
+ <configuration>
+ <verbose>true</verbose>
+ <endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint2</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para></section>
+</section>
+<section id="JBossWS-wsprovide_Ant_Task"><title>Ant Task</title><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSProvideTask</emphasis></para></para></note><para>The wsprovide ant task has the following attributes:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry> Attribute </entry><entry> Description </entry><entry> Default </entry></row></thead><tbody><row><entry>fork</entry><entry>Whether or not to run the generation task in a separate VM.</entry><entry>true</entry></row><row><entry>keep</entry><entry>Keep/Enable Java source code generation.</entry><entry>false</entry></row><row><entry>destdir</entry><entry>The output directory for generated artifacts.</entry><entry>"output"</entry></row><row><entry>resourcedestdir</entry><entry>The output dir!
ectory for resource artifacts (WSDL/XSD).</entry><entry>value of destdir</entry></row><row><entry>sourcedestdir</entry><entry>The output directory for Java source.</entry><entry>value of destdir</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row><row><entry>genwsdl</entry><entry>Whether or not to generate WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</entry><entry>false</entry></row><row><entry><emphasis role="bold">sei</emphasis></entry><entry><emphasis role="bold">Service Endpoint Implementation.</emphasis></entry></row><row><entry>classpath</entry><entry>The classpath that contains the service endpoint implementation.</entry><entry>"."</entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsprovide_Examples_651421"><title>Examples</title><para>Executing wsprovide in verbose mode with separate output directorie!
s for source, resources, and classes:</para><screen xml:space=!
"preserv
e"><target name="test-wsproivde" depends="init">
+ <taskdef name="wsprovide" classname="org.jboss.wsf.spi.tools.ant.WSProvideTask">
+ <classpath refid="core.classpath"/>
+ </taskdef>
+ <wsprovide
+ fork="false"
+ keep="true"
+ destdir="out"
+ resourcedestdir="out-resource"
+ sourcedestdir="out-source"
+ genwsdl="true"
+ verbose="true"
+ sei="org.jboss.test.ws.jaxws.jsr181.soapbinding.DocWrappedServiceImpl">
+ <classpath>
+ <pathelement path="${tests.output.dir}/classes"/>
+ </classpath>
+ </wsprovide>
+</target>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml
===================================================================
--- stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml (rev 0)
+++ stack/native/trunk/src/main/doc/JBossWS-wsrunclient.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsrunclient"><title>JBossWS-wsrunclient</title><para>wsrunclient is a command line tool that invokes a JBossWS JAX-WS Web Service client. It builds the correct classpath and endorsed libs for you. Feel free to use the code for this script to make your own shell scripts. It is open source after all.</para><section><title>Usage</title><screen xml:space="preserve"> wsrunclient [-classpath <additional class path>] <java-main-class> [arguments...]
+</screen></section>
+<section><title>Examples</title><para>Invoking a standalone JAX-WS client:</para><screen xml:space="preserve">wsrunclient echo.EchoClient</screen><para>Invoking a standalone JAX-WS client that uses external jars:</para><screen xml:space="preserve">wsrunclient -classpath jar1.jar:jar2.jar echo.EchoClient
+
+</screen></section>
+</chapter>
\ No newline at end of file
Modified: stack/native/trunk/src/main/scripts/assembly-bin-dist.xml
===================================================================
--- stack/native/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 18:02:20 UTC (rev 13201)
+++ stack/native/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 19:25:45 UTC (rev 13202)
@@ -55,6 +55,10 @@
<include>JBossORG-EULA.txt</include>
</includes>
</fileSet>
+ <fileSet>
+ <directory>target/docbook/publish</directory>
+ <outputDirectory>jbossws-native-bin-dist/docs</outputDirectory>
+ </fileSet>
<!-- deploy -->
<fileSet>
<directory>target/assembly/deploy-artifacts</directory>
14 years, 4 months
- 1
- 0
JBossWS SVN: r13201 - projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook.
by jbossws-commits＠lists.jboss.org
Author: alessio.soldano(a)jboss.com
Date: 2010-11-02 14:02:20 -0400 (Tue, 02 Nov 2010)
New Revision: 13201
Added:
projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSCXFDocLinkFilter.java
projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSNativeDocLinkFilter.java
Modified:
projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/Magnolia2DocBook.java
Log:
Making filter configurable
Added: projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSCXFDocLinkFilter.java
===================================================================
--- projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSCXFDocLinkFilter.java (rev 0)
+++ projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSCXFDocLinkFilter.java 2010-11-02 18:02:20 UTC (rev 13201)
@@ -0,0 +1,65 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2010, Red Hat Middleware LLC, and individual contributors
+ * as indicated by the @author tags. See the copyright.txt file in the
+ * distribution for a full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.util.magnolia2docbook;
+
+import java.net.URL;
+import java.util.LinkedList;
+import java.util.List;
+
+public class JBossWSCXFDocLinkFilter implements LinkFilter
+{
+ private static final List<String> allowedPages = new LinkedList<String>();
+ static
+ {
+ allowedPages.add("JBossWS-QuickStart".toLowerCase());
+ allowedPages.add("JBossWS-UserGuide".toLowerCase());
+ allowedPages.add("JBossWS-StackCXFUserGuide".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSTools".toLowerCase());
+ allowedPages.add("JBossWS-wsconsume".toLowerCase());
+ allowedPages.add("JBossWS-wsprovide".toLowerCase());
+ allowedPages.add("JBossWS-wsrunclient".toLowerCase());
+ allowedPages.add("JBossWS-Authentication".toLowerCase());
+ allowedPages.add("JBossWS-Securetransport".toLowerCase());
+ allowedPages.add("JBossWS-Endpointmanagement".toLowerCase());
+ allowedPages.add("JBossWS-Recordsmanagement".toLowerCase());
+ allowedPages.add("JBossWS-CXFWS-Addressingtutorial".toLowerCase());
+ allowedPages.add("JBossWS-CXFWS-ReliableMessagingtutorial".toLowerCase());
+ allowedPages.add("JBossWS-CXFJMStransporttutorial".toLowerCase());
+ allowedPages.add("JBossWS-Articlesandspecs".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSAnnotations".toLowerCase());
+ }
+
+ @Override
+ public boolean accept(URL url)
+ {
+ String path = url.getPath() != null ? url.getPath().toLowerCase() : "";
+ for (String p : allowedPages)
+ {
+ if (path.contains(p))
+ {
+ return true;
+ }
+ }
+ return false;
+ }
+
+}
Added: projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSNativeDocLinkFilter.java
===================================================================
--- projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSNativeDocLinkFilter.java (rev 0)
+++ projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/JBossWSNativeDocLinkFilter.java 2010-11-02 18:02:20 UTC (rev 13201)
@@ -0,0 +1,70 @@
+/*
+ * JBoss, Home of Professional Open Source.
+ * Copyright 2010, Red Hat Middleware LLC, and individual contributors
+ * as indicated by the @author tags. See the copyright.txt file in the
+ * distribution for a full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.jboss.util.magnolia2docbook;
+
+import java.net.URL;
+import java.util.LinkedList;
+import java.util.List;
+
+public class JBossWSNativeDocLinkFilter implements LinkFilter
+{
+ private static final List<String> allowedPages = new LinkedList<String>();
+ static
+ {
+ allowedPages.add("JBossWS-QuickStart".toLowerCase());
+ allowedPages.add("JBossWS-UserGuide".toLowerCase());
+ allowedPages.add("JBossWS-NativeUserGuide".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSTools".toLowerCase());
+ allowedPages.add("JBossWS-wsconsume".toLowerCase());
+ allowedPages.add("JBossWS-wsprovide".toLowerCase());
+ allowedPages.add("JBossWS-wsrunclient".toLowerCase());
+ allowedPages.add("JBossWS-Authentication".toLowerCase());
+ allowedPages.add("JBossWS-Securetransport".toLowerCase());
+ allowedPages.add("JBossWS-Endpointmanagement".toLowerCase());
+ allowedPages.add("JBossWS-Recordsmanagement".toLowerCase());
+ allowedPages.add("JBossWS-NativeWS-Addressingtutorial".toLowerCase());
+ allowedPages.add("JBossWS-NativeWS-ReliableMessagingtutorial".toLowerCase());
+ allowedPages.add("JBossWS-Articlesandspecs".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSAnnotations".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSEndpointConfiguration".toLowerCase());
+ allowedPages.add("JBossWS-JAX-WSClientConfiguration".toLowerCase());
+ allowedPages.add("JBossWS-WS-Securityoptions".toLowerCase());
+ allowedPages.add("JBossWS-Advancedsamples".toLowerCase());
+ allowedPages.add("JBossWS-Asynchronousinvocationssample".toLowerCase());
+ allowedPages.add("JBossWS-Securityandattachmentssample".toLowerCase());
+ }
+
+ @Override
+ public boolean accept(URL url)
+ {
+ String path = url.getPath() != null ? url.getPath().toLowerCase() : "";
+ for (String p : allowedPages)
+ {
+ if (path.contains(p))
+ {
+ return true;
+ }
+ }
+ return false;
+ }
+
+}
Modified: projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/Magnolia2DocBook.java
===================================================================
--- projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/Magnolia2DocBook.java 2010-11-02 18:00:03 UTC (rev 13200)
+++ projects/magnolia2docbook/src/org/jboss/util/magnolia2docbook/Magnolia2DocBook.java 2010-11-02 18:02:20 UTC (rev 13201)
@@ -37,8 +37,26 @@
public static void main(String[] args) throws Exception
{
String startPage = args[0];
- //LinkFilter filter = new JBossWSLinkFilter(); //TODO read from args
- LinkFilter filter = new AS6JBossWSDocLinkFilter();
+ String filterName = args[1];
+ LinkFilter filter;
+ if ("CXF".equalsIgnoreCase(filterName))
+ {
+ filter = new JBossWSCXFDocLinkFilter();
+ }
+ else if ("NATIVE".equalsIgnoreCase(filterName))
+ {
+ filter = new JBossWSNativeDocLinkFilter();
+ }
+ else if ("AS6".equalsIgnoreCase(filterName))
+ {
+ filter = new AS6JBossWSDocLinkFilter();
+ }
+ else
+ {
+ System.out.println("Unknown filter '" + filterName + "', using JBossWS default one.");
+ filter = new JBossWSLinkFilter();
+ }
+ System.out.println("Filter: " + filter);
Magnolia2DocBook m2d = new Magnolia2DocBook();
m2d.run(new URL(startPage), false, "output", filter);
14 years, 4 months
- 1
- 0
JBossWS SVN: r13200 - in stack/cxf/trunk: src/main and 2 other directories.
by jbossws-commits＠lists.jboss.org
Author: alessio.soldano(a)jboss.com
Date: 2010-11-02 14:00:03 -0400 (Tue, 02 Nov 2010)
New Revision: 13200
Added:
stack/cxf/trunk/src/main/doc/
stack/cxf/trunk/src/main/doc/Author_Group.xml
stack/cxf/trunk/src/main/doc/Book_Info.xml
stack/cxf/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
stack/cxf/trunk/src/main/doc/JBossWS-Authentication.xml
stack/cxf/trunk/src/main/doc/JBossWS-CXF.xml
stack/cxf/trunk/src/main/doc/JBossWS-CXFJMStransporttutorial.xml
stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-Addressingtutorial.xml
stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-ReliableMessagingtutorial.xml
stack/cxf/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
stack/cxf/trunk/src/main/doc/JBossWS-QuickStart.xml
stack/cxf/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
stack/cxf/trunk/src/main/doc/JBossWS-Securetransport.xml
stack/cxf/trunk/src/main/doc/JBossWS-StackCXFUserGuide.xml
stack/cxf/trunk/src/main/doc/JBossWS-UserGuide.xml
stack/cxf/trunk/src/main/doc/JBossWS-wsconsume.xml
stack/cxf/trunk/src/main/doc/JBossWS-wsprovide.xml
stack/cxf/trunk/src/main/doc/JBossWS-wsrunclient.xml
Modified:
stack/cxf/trunk/pom.xml
stack/cxf/trunk/src/main/scripts/assembly-bin-dist.xml
Log:
[JBWS-2215] Adding docbook sources and generating documentation during binary distro creation
Modified: stack/cxf/trunk/pom.xml
===================================================================
--- stack/cxf/trunk/pom.xml 2010-11-02 14:28:01 UTC (rev 13199)
+++ stack/cxf/trunk/pom.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -1197,6 +1197,25 @@
</dependency>
</dependencies>
</plugin>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.1.2</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.0.0</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ </plugin>
</plugins>
</pluginManagement>
@@ -1279,6 +1298,49 @@
</descriptors>
</configuration>
</plugin>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>resources</goal>
+ <goal>generate</goal>
+ </goals>
+ <phase>package</phase>
+ </execution>
+ </executions>
+ <configuration>
+ <sourceDocumentName>JBossWS-CXF.xml</sourceDocumentName>
+ <sourceDirectory>src/main/doc</sourceDirectory>
+ <imageResource>
+ <directory>src/main/doc</directory>
+ <includes>
+ <include>images/*</include>
+ </includes>
+ </imageResource>
+ <formats>
+ <!--format>
+ <formatName>pdf</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>JBossWS-CXF_Guide.pdf</finalName>
+ </format-->
+ <format>
+ <formatName>html</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <format>
+ <formatName>html_single</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ </options>
+ </configuration>
+ </plugin>
</plugins>
</build>
</profile>
Added: stack/cxf/trunk/src/main/doc/Author_Group.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/Author_Group.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/Author_Group.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,17 @@
+<?xml version='1.0'?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ ]>
+<authorgroup>
+ <author>
+ <firstname>Alessio</firstname>
+ <surname>Soldano</surname>
+ </author>
+ <author>
+ <firstname>Richard</firstname>
+ <surname>Opalka</surname>
+ </author>
+ <author>
+ <firstname>Jim</firstname>
+ <surname>Ma</surname>
+ </author>
+</authorgroup>
Added: stack/cxf/trunk/src/main/doc/Book_Info.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/Book_Info.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/Book_Info.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,14 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<bookinfo>
+<title>JBossWS-CXF Guide</title>
+ <subtitle>JBoss Web Services with Apache CXF based stack</subtitle>
+ <productname>JBossWS-CXF</productname>
+ <!-- <pubdate>Nov 2010</pubdate> -->
+ <abstract>
+ <para>This book is the guide to JBoss Web Services with Apache CXF based stack. It covers information, details and usage of JBossWS-CXF stack, as well as some tutorials / examples.</para>
+ </abstract>
+ <!-- <subtitle>Authors</subtitle>-->
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</bookinfo>
Added: stack/cxf/trunk/src/main/doc/JBossWS-Articlesandspecs.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-Articlesandspecs.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-Articlesandspecs.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Articlesandspecs"><title>JBossWS-Articlesandspecs</title><section><title>J2EE-5.0 Web Services Specifications</title><itemizedlist><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=244">J2EE-5.0 - Java2 Enterprise Edition Specification (JSR244)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web Services (JSR921)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=220">EJB-3.0 - Enterprise Java Beans (JSR220)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=224">JAXWS-2.0 - Java API for XML-Based Web Services (JSR224)</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=222">JAXB-2.0 - Java Architecture for XML Binding (JSR222)</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-!
part1">SOAP-1.2 - SOAP Messaging Framework</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-part0">SOAP-1.2 Primer</ulink> </para></listitem><listitem><para> <ulink url="http://schemas.xmlsoap.org/wsdl/soap12">WSDL 1.1 Binding Extension for SOAP 1.2</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20">WSDL-2.0 - Part 1: Core Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20-extensions">WSDL-2.0 - Part 2: Predefined Extensions</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl20-bindings">WSDL-2.0 - Part 3: Bindings</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/2002/ws/desc/wsdl20-primer">WSDL-2.0 Primer</ulink> </para></listitem><listitem><para> <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.1.html">BP-1.1 - Basic Profile</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/de!
tail?id=181">JSR181 - Web Services Metadata</ulink> </para></l!
istitem>
<listitem><para> <ulink url="http://www.ws-i.org/Profiles/AttachmentsProfile-1.0.html">WS-I Attachments Profile 1.0</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/soap12-mtom/">SOAP Message Transmission Optimization Mechanism (MTOM)</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xop10/">XML-binary Optimized Packaging (XOP)</ulink></para></listitem></itemizedlist></section>
+<section><title>J2EE-1.4 Web Services Specifications</title><itemizedlist><listitem><para> <ulink url="http://java.sun.com/j2ee/1.4/index.jsp">J2EE-1.4 - Java 2 Platform, Enterprise Edition (J2EE) 1.4</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=921">WS4EE-1.1 - Enterprise Web Services</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=153">EJB-2.1 - Enterprise Java Beans</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=101">JAXRPC-1.1 - Java API for XML-based RPC</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=67">SAAJ-1.2 - SOAP with Attachments</ulink> </para></listitem><listitem><para> <ulink url="http://www.jcp.org/en/jsr/detail?id=93">JAXR-1.0 - Java API for XML Registries</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1 - Simple Object Acc!
ess Protocol</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/wsdl">WSDL-1.1 - Web Services Description Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/REC-xml/">XML-1.0 - Extensible Markup Language</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-1/">XMLSchema - Structures</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-2/">XMLSchema - Data Types</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/xmlschema-0">XMLSchema Primer</ulink> </para></listitem><listitem><para> <ulink url="http://www.w3.org/TR/REC-xml-names">XMLNS - Namespaces in XML</ulink> </para></listitem><listitem><para> <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0.html">BP-1.0 - Basic Profile</ulink></para></listitem></itemizedlist></section>
+<section><title>Optional advanced Web Services specifications</title><itemizedlist><listitem><para> <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobsp...">MSDN Web Services Specifications Index Page</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-330">WS-Distributed Managment</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-326">WS-Notification</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-76">WS-ReliableMessaging</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-329">WS-Resource</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.com/jira/browse/JBWS-36">WS-Transaction</ulink> </para></listitem><listitem><para> <ulink url="http://jira.jboss.org/jira/browse/JBWS-447">WS-BPEL</ulink></para></listitem></itemizedlist><vari!
ablelist/><para>Please provide feedback on your needs of these optional WS specifications as this will influence what we will put on the <ulink url="http://jira.jboss.org/jira/browse/JBWS?report=com.atlassian.jira.plugin.s...">JBossWS roadmap</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-Authentication.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-Authentication.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-Authentication.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Authentication"><title>JBossWS-Authentication</title><para>This page explains the simplest way to authenticate a web service user with JBossWS.</para><para>First we secure the access to the SLSB as we would do for normal (non web service) invocations: this can be easily done through the @RolesAllowed, @PermitAll, @DenyAll annotation. The allowed user roles can be set with these annotations both on the bean class and on any of its business methods.</para><screen xml:space="preserve">@Stateless
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly POJO endpoints are secured the same way as we do for normal web applications in web.xml:</para><screen xml:space="preserve"> <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role></screen><section><title>Define the security domain</title><para>Next, define the security domain for this deployment. This is performed using the <ulink url="http://community.jboss.org/docs/DOC-13972#SecurityDomain">@SecurityDomain</ulink> annotation for EJB3 endpoints</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>or modifying the jboss-web.xml for POJO endpoints</para><screen xml:space="preserve"><jboss-web>
+ <security-domain>java:/jaas/JBossWS</security-domain>
+</jboss-web>
+</screen><para>The JBossWS security context is configured in login-config.xml and uses the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=UsersRolesLoginModule">UsersRolesLoginModule</ulink>. As a matter of fact login-config.xml, that lives in the server config dir, contains this security domain definition:</para><screen xml:space="preserve"> <!--
+ A template configuration for the JBossWS security domain.
+ This defaults to the UsersRolesLoginModule the same as other and should be
+ changed to a stronger authentication mechanism as required.
+ -->
+ <application-policy name="JBossWS">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="usersProperties">props/jbossws-users.properties</module-option>
+ <module-option name="rolesProperties">props/jbossws-roles.properties</module-option>
+ <module-option name="unauthenticatedIdentity">anonymous</module-option>
+ </login-module>
+ </authentication>
+ </application-policy>
+</screen><para>Of course you can define and use your own security domain as well as your login module (in order to check for users' identity querying a database for example).</para></section>
+<section><title>Use BindingProvider to set principal/credential</title><para>A web service client may use the javax.xml.ws.BindingProvider interface to set the username/password combination</para><screen xml:space="preserve">URL wsdlURL = <emphasis role="bold">new</emphasis> File("resources/jaxws/samples/context/WEB-INF/wsdl/TestEndpoint.wsdl").toURL();
+QName qname = <emphasis role="bold">new</emphasis> QName("http://org.jboss.ws/jaxws/context", "TestEndpointService");
+Service service = Service.create(wsdlURL, qname);
+port = (TestEndpoint)service.getPort(TestEndpoint.class);
+
+BindingProvider bp = (BindingProvider)port;
+bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY, "kermit");
+bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, "thefrog");
+</screen></section>
+<section><title>Using HTTP Basic Auth for security</title><para>To enable HTTP Basic authentication you use the <ulink url="http://community.jboss.org/docs/DOC-13972#WebContext">@WebContext</ulink> annotation on the bean class</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext(contextRoot="/my-cxt", urlPattern="/*", authMethod="BASIC", transportGuarantee="NONE", secureWSDLAccess=<emphasis role="bold">false</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>For POJO endpoints, we modify the web.xml adding the auth-method element:</para><screen xml:space="preserve"> <login-config>
+ <auth-method>BASIC</auth-method>
+ <realm-name>Test Realm</realm-name>
+ </login-config>
+</screen></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-CXF.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-CXF.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-CXF.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+
+<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+<part id="Main documentation">
+ <title>Main Documentation</title>
+ <partintro>
+ <para>
+ JBossWS-CXF is basically the JBoss Web Service integration with Apache CXF stack. This way additional JBoss features and customizations are added on top of already
+ existing Apache CXF functionalities. In particular the integration provides technologies for allowing the JBoss Application Server to support JavaEE requirements
+ in terms of Web Services functionalities.
+ </para>
+ <para>
+ Below you find the essential documentation on the current JBossWS-CXF release. That covers a quick start, a full user guide and tooling. You can read more on
+ JBoss Web Service Framework on the JBossWS Wiki at <ulink url="http://community.jboss.org/wiki/JBossWS">http://community.jboss.org/wiki/JBossWS</ulink>.
+ </para>
+ <para>
+ Please note, the wiki also offers a <ulink url="http://www.jboss.org/community/docs/DOC-13531">Guided Tour</ulink> along the JBossWS documentation, for those who
+ don't know where to start from when dealing with webservices in general.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-QuickStart.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-UserGuide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" /> <!-- remove WSF stuff from generated page -->
+ <xi:include href="JBossWS-StackCXFUserGuide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSTools.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsconsume.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsprovide.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-wsrunclient.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Additional documentation">
+ <title>Additional documentation</title>
+ <partintro>
+ <para>
+ This section of the book provides documentation on common additional user requirements, like enabling authentication, securing the transport, etc.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-Authentication.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Securetransport.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Endpointmanagement.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Recordsmanagement.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+
+<part id="Samples, Tutorials, references">
+ <title>Samples & Tutorials</title>
+ <partintro>
+ <para>
+ Below you find few tutorials on WS-* technologies usage as well as a brief list of reference links and the list of supported JAX-WS annotations.
+ </para>
+ </partintro>
+ <xi:include href="JBossWS-CXFWS-Addressingtutorial.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-CXFWS-ReliableMessagingtutorial.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-CXFJMStransporttutorial.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-Articlesandspecs.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="JBossWS-JAX-WSAnnotations.xml" encoding="UTF-8" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</part>
+
+</book>
Added: stack/cxf/trunk/src/main/doc/JBossWS-CXFJMStransporttutorial.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-CXFJMStransporttutorial.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-CXFJMStransporttutorial.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-CXFJMStransporttutorial"><title>JBossWS-CXFJMStransporttutorial</title><para>JBossWS-CXF supports JMS Transport to transfer SOAP messages. There is a testcase in the codebase to demonstrate this ability, available <ulink url="http://anonsvn.jboss.org/repos/jbossws/stack/cxf/tags/jbossws-cxf-3.4.0.C...">here</ulink>. In this tutorial, we will use a wsdl first web service example to show you how to enable this feature in JBossWS.</para><para> </para><para/><section id="JBossWS-CXFJMStransporttutorial_WSDL"><title>WSDL</title><screen xml:space="preserve">
+<wsdl:definitions name="OrganizationJMSEndpointService" targetNamespace="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" xmlns:jms="<ulink url="http://cxf.apache.org/transports/jms">http://cxf.apache.org/transports/jms</ulink>" xmlns:ns1="<ulink url="http://schemas.xmlsoap.org/wsdl/soap/http">http://schemas.xmlsoap.org/wsdl/soap/http</ulink>" xmlns:soap="<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>" xmlns:tns="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" xmlns:wsdl="<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>" xmlns:xsd="<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>">
+ <wsdl:message name="getContactInfoResponse">
+ <wsdl:part name="return" type="xsd:string">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="getContactInfo">
+ <wsdl:part name="arg0" type="xsd:string">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:portType name="Organization">
+ <wsdl:operation name="getContactInfo">
+ <wsdl:input message="tns:getContactInfo" name="getContactInfo">
+ </wsdl:input>
+ <wsdl:output message="tns:getContactInfoResponse" name="getContactInfoResponse">
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="HTTPSoapBinding" type="tns:Organization">
+ <soap:binding style="rpc" transport="<ulink url="http://schemas.xmlsoap.org/soap/http">http://schemas.xmlsoap.org/soap/http</ulink>"/>
+ <wsdl:operation name="getContactInfo">
+ <soap:operation soapAction="" style="rpc"/>
+ <wsdl:input name="getContactInfo">
+ <soap:body namespace="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="getContactInfoResponse">
+ <soap:body namespace="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+
+ <wsdl:binding name="JMSSoapBinding" type="tns:Organization">
+ <soap:binding style="rpc" transport="<ulink url="http://cxf.apache.org/transports/jms">http://cxf.apache.org/transports/jms</ulink>"/>
+ <wsdl:operation name="getContactInfo">
+ <soap:operation soapAction="" style="rpc"/>
+ <wsdl:input name="getContactInfo">
+ <soap:body namespace="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="getContactInfoResponse">
+ <soap:body namespace="<ulink url="http://org.jboss.ws/samples/jmstransport">http://org.jboss.ws/samples/jmstransport</ulink>" use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+
+
+ <wsdl:service name="OrganizationService">
+ <wsdl:port binding='tns:HTTPSoapBinding' name='HttpEndpointPort'>
+ <soap:address location='<ulink url="http://@jboss.bind.address@:8080/jaxws-samples-jmstransport'/">http://@jboss.bind.address@:8080/jaxws-samples-jmstransport'/</ulink>>
+ </wsdl:port>
+ <wsdl:port binding="tns:JMSSoapBinding" name="JmsEndpointPort">
+ <jms:address
+ destinationStyle="queue"
+ jndiConnectionFactoryName="ConnectionFactory"
+ jndiDestinationName="queue/RequestQueue"
+ jndiReplyDestinationName="queue/ResponseQueue">
+ >
+ </jms:address>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions></screen><para> </para><para>Apache CXF defines the jms wsdl extension, so the jms queue name or other information about jms in wsdl port can be parsed to send or receive jms message. Check this wiki page to see what jms attributes you can defined in WSDL. In this wsdl, we define two queues to send and receive the soap message. CXF uses JNDI to look up the jms ConnectionFactory, so we may also need to provide the JNDI properties as the following example :</para><para> </para><screen xml:space="preserve"><jms:address
+ destinationStyle="queue"
+ jndiConnectionFactoryName="ConnectionFactory"
+ jndiDestinationName="queue/RequestQueue"
+ jndiReplyDestinationName="queue/ResponseQueue"
+ >
+ <jms:JMSNamingProperty name="java.naming.factory.initial"
+ value="org.jnp.interfaces.NamingContextFactory"/>
+ <jms:JMSNamingProperty name="java.naming.provider.url"
+ value="jnp://localhost:1099"/>
+</jms:address></screen><para> </para></section>
+<section id="JBossWS-CXFJMStransporttutorial_Service_Implementation"><title>Service Implementation</title><para> </para><para>After generated code from this wsdl , we wrote two class to implement this interface for this two ports . We annotate the portName in annotation to tell web service stack which transport this service uses :</para><para> </para><screen xml:space="preserve">@WebService (serviceName="OrganizationService", portName="HttpEndpointPort",wsdlLocation = "WEB-INF/wsdl/jmstransport.wsdl",targetNamespace = "http://org.jboss.ws/samples/jmstransport", endpointInterface="org.jboss.test.ws.jaxws.samples.jmstransport.Organization")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> OrganizationHttpEndpoint <emphasis role="bold">implements</emphasis> Organization
+{
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String getContactInfo(String organization)
+ {
+ <emphasis role="bold">return</emphasis> "The '" + organization + "' boss is currently out of office, please call again.";
+ }
+}
+
+
+
+
+</screen><para> </para><para> </para><para> </para><screen xml:space="preserve">@WebService (serviceName="OrganizationService",portName="JmsEndpointPort", wsdlLocation = "WEB-INF/wsdl/jmstransport.wsdl", targetNamespace = "http://org.jboss.ws/samples/jmstransport", endpointInterface="org.jboss.test.ws.jaxws.samples.jmstransport.Organization")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> OrganizationJmsEndpoint <emphasis role="bold">implements</emphasis> Organization
+{
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String getContactInfo(String organization)
+ {
+ <emphasis role="bold">return</emphasis> "The '" + organization + "' boss is currently out of office, please call again.";
+ }
+}
+
+
+
+
+</screen><para> </para></section>
+<section id="JBossWS-CXFJMStransporttutorial_webxml"><title>web.xml</title><para> </para><screen xml:space="preserve"><web-app xmlns="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink> <ulink url="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd</ulink>"
+ version="2.4">
+
+ <servlet>
+ <servlet-name>OrganizationService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.jmstransport.OrganizationHttpEndpoint</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>OrganizationService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping></web-app></screen><para> </para><para>It is almost the same as the usual web.xml to deploy a web service except the <load-on-startup> servlet initializeparameter. This is for jms service start ready when deployment, no need to wait until the first servlet request to start the jms endpoint.</para><para> </para></section>
+<section id="JBossWS-CXFJMStransporttutorial_jbosswscxfxml"><title>jbossws-cxf.xml</title><para>In addition to web.xml, the jbossws-cxf.xml is needed to actually pass in cxf to start this two port.</para><para> </para><screen xml:space="preserve"><beans xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>' xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jms="<ulink url="http://cxf.apache.org/transports/jms">http://cxf.apache.org/transports/jms</ulink>"
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xsi:schemaLocation='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink> <ulink url="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd</ulink>
+ <ulink url="http://www.w3.org/2006/07/ws-policy">http://www.w3.org/2006/07/ws-policy</ulink> <ulink url="http://www.w3.org/2006/07/ws-policy.xsd">http://www.w3.org/2006/07/ws-policy.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink> <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>
+ <ulink url="http://cxf.apache.org/transports/jms">http://cxf.apache.org/transports/jms</ulink> <ulink url="http://cxf.apache.org/schemas/configuration/jms.xsd">http://cxf.apache.org/schemas/configuration/jms.xsd</ulink>'>
+
+ <import resource="classpath:META-INF/cxf/cxf-extension-jms.xml"/>
+ <jaxws:endpoint id='SOAPQueryService'
+ implementor='org.jboss.test.ws.jaxws.samples.jmstransport.OrganizationHttpEndpoint'
+ >
+ <jaxws:invoker>
+ <bean class='org.jboss.wsf.stack.cxf.InvokerJSE'/>
+ </jaxws:invoker>
+ </jaxws:endpoint>
+
+ <jaxws:endpoint id='JMSQueryService'
+ implementor='org.jboss.test.ws.jaxws.samples.jmstransport.OrganizationJmsEndpoint'
+ transportId="<ulink url="http://cxf.apache.org/transports/jms">http://cxf.apache.org/transports/jms</ulink>">
+ </jaxws:endpoint>
+</beans></screen><para> </para><para><emphasis role="bold">Note: </emphasis>the import resource is the JmsTransportFactory configuration . It is required to jms transport enablement .</para><para> </para><para>Below gives the war file directory structure to make it more clear what inside :</para><screen xml:space="preserve">
+|-- jmstransport-sample.war
+`-- WEB-INF
+ |-- classes
+ | `-- org
+ | `-- jboss
+ | `-- test
+ | `-- ws
+ | `-- jaxws
+ | `-- samples
+ | `-- jmstransport
+ | |-- JMSTransportTestCase$ResponseListener.class
+ | |-- JMSTransportTestCase.class
+ | |-- Organization.class
+ | |-- OrganizationHttpEndpoint.class
+ | `-- OrganizationJmsEndpoint.class
+ |-- jboss-web.xml
+ |-- jbossws-cxf.xml
+ |-- web.xml
+ `-- wsdl
+ `-- jmstransport.wsdl</screen></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-Addressingtutorial.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-Addressingtutorial.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-Addressingtutorial.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,170 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-CXFWS-Addressingtutorial"><title>JBossWS-CXFWS-Addressingtutorial</title><para><ulink url="http://incubator.apache.org/cxf/">Apache CXF</ulink> comes with support for <ulink url="http://www.w3.org/TR/ws-addr-core/">WS-Addressing 1.0</ulink>. In this sample we will show how to create client and endpoint communicating each other using this feature.</para><para>Creating WS-Addressing based service and client is very simple. User needs to create regular JAX-WS service and client first. The last step is to configure the addressing on both sides.</para><para> </para><para/><para> </para><section id="JBossWS-CXFWS-Addressingtutorial_The_Service"><title>The Service</title><para>We will start with the following endpoint implementation (bottom-up approach):</para><para> </para><screen xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para>The endpoint implements the following endpoint interface:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> ServiceIface
+{
+ @WebMethod
+ String sayHello();
+}
+</screen><para>Let's say that compiled endpoint and interface classes are located in directory <emphasis role="bold">/home/username/wsa/cxf/classes</emphasis>. Our next step is to generate JAX-WS artifacts and WSDL that will be part of endpoint archive.</para><para> </para></section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating WSDL and JAX-WS Endpoint Artifacts</title><para>We will use <emphasis role="bold">wsprovide</emphasis> commandline tool to generate WSDL and JAX-WS artifacts. Here's the command:</para><screen xml:space="preserve">cd JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsa/cxf/classes \
+ --output=/home/username/wsa/cxf/wsprovide/generated/classes \
+ --resource=/home/username/wsa/cxf/wsprovide/generated/wsdl \
+ --source=/home/username/wsa/cxf/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsa/cxf/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws
+SayHello.class SayHelloResponse.class
+
+# java sources
+ls /home/username/wsa/cxf/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsa/jaxws
+SayHello.java SayHelloResponse.java
+
+# contract artifacts
+ls /home/username/wsa/cxf/wsprovide/generated/wsdl/
+AddressingService.wsdl</screen><para>All aforementioned generated artifacts will be part of endpoint archive. But before we will create the endpoint archive we need to reference generated WSDL from endpoint. To achieve that we will use <emphasis role="bold">wsdlLocation</emphasis> annotation attribute. Here's the updated endpoint implementation before packaging it to the war file:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para> </para><para>Created endpoint war archive consists of the following entries:</para><para> </para><screen xml:space="preserve">jar -tvf jaxws-samples-wsa.war
+ 0 Mon Apr 21 20:39:30 CEST 2008 META-INF/
+ 106 Mon Apr 21 20:39:28 CEST 2008 META-INF/MANIFEST.MF
+ 0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/
+ 593 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/web.xml
+ 0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/classes/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/
+ 374 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceIface.class
+ 954 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceImpl.class
+ 0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
+ 703 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHello.class
+ 1074 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHelloResponse.class
+ 0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/wsdl/
+ 2378 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/wsdl/AddressingService.wsdl
+</screen><para>The content of web.xml file is:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?><web-app
+ version="2.5" xmlns="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/javaee">http://java.sun.com/xml/ns/javaee</ulink> <ulink url="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd</ulink>">
+ <servlet>
+ <servlet-name>AddressingService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>AddressingService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app>
+</screen></section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Writing_Regular_JAXWS_Client"><title>Writing Regular JAX-WS Client</title><para>The following is the regular JAX-WS client using endpoint interface to lookup the webservice:</para><para> </para><para>package org.jboss.test.ws.jaxws.samples.wsa;</para><screen xml:space="preserve">import java.net.URL;import javax.xml.namespace.QName;import javax.xml.ws.Service;public final class SimpleServiceTestCase{ private final String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService"; public static void main(String[] args) throws Exception { // create service QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService"); URL wsdlURL = new URL(serviceURL + "?wsdl"); Service service = Service.create(wsdlURL, serviceName); ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class); �!
� // invoke method proxy.sayHello(); } }</screen><para>Now we have both endpoint and client implementation but without WS-Addressing in place. Our next goal is to turn on the WS-Addressing feature.</para></section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Turning_on_WSAddressing_10"><title>Turning on WS-Addressing 1.0</title><para>In order to turn on WS-Addressing in JBossWS-CXF integration the last two steps are remaining:</para><itemizedlist><listitem><para>annotate service endpoint with @Addressing annotation</para></listitem><listitem><para>modify client to configure WS-Addressing using JAX-WS webservice feature</para></listitem></itemizedlist><para> </para><section id="JBossWS-CXFWS-Addressingtutorial_Updating_Endpoint_Code_to_Configure_WSAddressing"><title>Updating Endpoint Code to Configure WS-Addressing</title><para>Now we need to update endpoint implementation to configure WS-Addressing. Here's the updated endpoint code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.xml.ws.soap.Addressing;
+
+@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+@Addressing(enabled=true, required=<emphasis role="bold">true</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ <emphasis role="bold">public</emphasis> String sayHello()
+ {
+ <emphasis role="bold">return</emphasis> "Hello World!";
+ }
+}
+</screen><para>As users can see we added JAX-WS 2.1 <emphasis role="bold">Addressing</emphasis> annotation to configure WS-Addressing. The next step is to repackage the endpoint archive to apply this change.</para><para> </para></section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Updating_Client_Code_to_Configure_WSAddressing"><title>Updating Client Code to Configure WS-Addressing</title><para>Now we need to update client implementation as well to configure WS-Addressing. Here's the updated client code:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsa;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> javax.xml.ws.soap.AddressingFeature;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> AddressingTestCase
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://" + getServerHost() + ":8080/jaxws-samples-wsa/AddressingService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ // construct proxy
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsaddressing", "AddressingService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class, <emphasis role="bold">new</emphasis> AddressingFeature());
+ // invoke method
+ assertEquals("Hello World!", proxy.sayHello());
+ }
+
+}
+</screen><para>And that's all. Now we have both JAX-WS client and endpoint communicating each other using WS-Addressing feature.</para><para> </para><para> </para></section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Leveraging_WSAddressing_Policy"><title>Leveraging WS-Addressing Policy</title><para>An option you can also evaluate to simplify both client and server deployment, is to let the server engine generate and publish the wsdl contract instead of using the one mentioned above: (please note the removal of wsdlLocation attribute in the @WebService annotation)</para><para> </para><screen xml:space="preserve">@WebService
+(
+ portName = "AddressingServicePort",
+ serviceName = "AddressingService",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsaddressing",
+ endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
+)
+@Addressing(enabled=true, required=<emphasis role="bold">true</emphasis>)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServiceImpl <emphasis role="bold">implements</emphasis> ServiceIface
+{
+ ...
+}
+</screen><para> </para><para>This way the endpoint is published with a contract containing a WS-Addressing Policy that tells clients addressing needs to be on.</para><para> </para><screen xml:space="preserve"><wsp:Policy wsu:Id="AddressingServiceSoapBinding_WSAM_Addressing_Policy">
+ <wsam:Addressing>
+ <wsp:Policy/>
+ </wsam:Addressing>
+</wsp:Policy></screen><para> </para><para>The client can then simply do as follows:</para><para> </para><screen xml:space="preserve">Service service = Service.create(wsdlURL, serviceName);
+ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class);
+// invoke method
+</screen><para> </para><para>No need for setting the AddressingFeature, the policy engine takes care of enabling WS-Addressing to match the policy advertised by the server.</para><para> </para></section>
+</section>
+<section id="JBossWS-CXFWS-Addressingtutorial_Sample_Sources"><title>Sample Sources</title><para>All sources from this tutorial are part of JBossWS-CXF testsuite.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-ReliableMessagingtutorial.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-ReliableMessagingtutorial.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-CXFWS-ReliableMessagingtutorial.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,319 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-CXFWS-ReliableMessagingtutorial"><title>JBossWS-CXFWS-ReliableMessagingtutorial</title><para><ulink url="http://incubator.apache.org/cxf/">Apache CXF</ulink> comes with support for <ulink url="http://specs.xmlsoap.org/ws/2005/02/rm/ws-reliablemessaging.pdf">WS-RM 1.0</ulink>. In this sample we will show how to create client and endpoint communicating each other using WS-RM 1.0. The sample uses <ulink url="http://www.w3.org/2006/07/ws-policy/">WS-Policy</ulink> specification to configure WS-RM.</para><para>Creating the WS-RM based service and client is very simple. User needs to create regular JAX-WS service and client first. The last step is to configure WSRM.</para><para/><section id="JBossWS-CXFWS-ReliableMessagingtutorial_The_service"><title>The service</title><para>We will start with the following endpoint implementation (bottom-up approach):</para><screen xml:space="preserve"><emphasis role="bold">package<!
/emphasis> org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>Let's say that compiled endpoint class is in directory <emphasis role="bold">/home/username/wsrm/cxf/classes</emphasis>. Our next step is to generate JAX-WS artifacts and WSDL.</para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Generating_WSDL_and_JAXWS_Endpoint_Artifacts"><title>Generating WSDL and JAX-WS Endpoint Artifacts</title><para>We will use <emphasis role="bold">wsprovide</emphasis> commandline tool to generate WSDL and JAX-WS artifacts. Here's the command:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsprovide.sh --keep --wsdl \
+ --classpath=/home/username/wsrm/cxf/classes \
+ --output=/home/username/wsrm/cxf/wsprovide/generated/classes \
+ --resource=/home/username/wsrm/cxf/wsprovide/generated/wsdl \
+ --source=/home/username/wsrm/cxf/wsprovide/generated/src \
+ org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsrm/cxf/wsprovide/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.class EchoResponse.class Ping.class
+
+# java sources
+ls /home/username/wsrm/cxf/wsprovide/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+Echo.java EchoResponse.java Ping.java
+
+# contract artifacts
+ls /home/username/wsrm/cxf/wsprovide/generated/wsdl/
+SimpleService.wsdl
+</screen><para>All aforementioned generated artifacts will be part of endpoint archive. But before we will create the endpoint archive we need to reference generated WSDL from endpoint. To achieve that we will use <emphasis role="bold">wsdlLocation</emphasis> annotation attribute. Here's the updated endpoint implementation before packaging it to the war file:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.service;
+
+<emphasis role="bold">import</emphasis> javax.jws.Oneway;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+
+@WebService
+(
+ name = "SimpleService",
+ serviceName = "SimpleService",
+ wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl",
+ targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceImpl
+{
+ @Oneway
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ System.out.println("ping()");
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String s)
+ {
+ System.out.println("echo(" + s + ")");
+ <emphasis role="bold">return</emphasis> s;
+ }
+}
+</screen><para>Created endpoint war archive consists of the following entries:</para><screen xml:space="preserve">jar -tvf jaxws-samples-wsrm.war
+ 0 Wed Apr 16 14:39:22 CEST 2008 META-INF/
+ 106 Wed Apr 16 14:39:20 CEST 2008 META-INF/MANIFEST.MF
+ 0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/
+ 591 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/web.xml
+ 0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/classes/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
+ 0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
+ 1235 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl.class
+ 997 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
+ 1050 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoResponse.class
+ 679 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
+ 0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/wsdl/
+ 2799 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
+</screen><para>The content of web.xml file is:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+
+<web-app
+ version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
+ <servlet>
+ <servlet-name>SimpleService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>SimpleService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+</web-app></screen></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Generating_JAXWS_Client_Artifacts"><title>Generating JAX-WS Client Artifacts</title><para>Before we will write regular JAX-WS client we need to generate client artifacts from WSDL. Here's the command to achieve that:</para><screen xml:space="preserve">cd $JBOSS_HOME/bin
+
+./wsconsume.sh --keep \
+ --package=org.jboss.test.ws.jaxws.samples.wsrm.generated \
+ --output=/home/username/wsrm/cxf/wsconsume/generated/classes \
+ --source=/home/username/wsrm/cxf/wsconsume/generated/src \
+ /home/username/wsrm/cxf/wsprovide/generated/wsdl/SimpleService.wsdl
+</screen><para>The above command generates the following artifacts:</para><screen xml:space="preserve"># compiled classes
+ls /home/username/wsrm/cxf/wsconsume/generated/classes/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.class ObjectFactory.class Ping.class SimpleService_Service.class
+EchoResponse.class package-info.class SimpleService.class SimpleService_SimpleServicePort_Client.class
+
+# java sources
+ls /home/username/wsrm/cxf/wsconsume/generated/src/org/jboss/test/ws/jaxws/samples/wsrm/generated/
+Echo.java ObjectFactory.java Ping.java SimpleService_Service.java
+EchoResponse.java package-info.java SimpleService.java SimpleService_SimpleServicePort_Client.java
+</screen><para>Now the last step is to write the regular JAX-WS client using generated artifacts.</para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Writing_Regular_JAXWS_Client"><title>Writing Regular JAX-WS Client</title><para>The following is the regular JAX-WS client using generated artifacts:</para><screen xml:space="preserve">package org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+import java.net.URL;
+import javax.xml.namespace.QName;
+import javax.xml.ws.Service;
+import org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+public final class SimpleServiceTestCase
+{
+
+ private static final String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ public static void main(String[] args) throws Exception
+ {
+ // create service
+ QName serviceName = new QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
+ URL wsdlURL = new URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+
+ // invoke methods
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+ }
+
+}
+</screen><para>Now we have both endpoint and client implementation but without WSRM in place. Our next goal is to turn on the WS-RM feature.</para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Turning_on_WSRM_10"><title>Turning on WS-RM 1.0</title><section id="JBossWS-CXFWS-ReliableMessagingtutorial_Extending_WSDL_Using_WSPolicy"><title>Extending WSDL Using WS-Policy</title><para>To activate WSRM on server side we need to extend the WSDL with WSRM and addressing policies. Here is how it looks like:</para><screen xml:space="preserve"><?xml version="1.0" encoding="UTF-8"?>
+<wsdl:definitions name="SimpleService" targetNamespace="<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>" xmlns:tns="<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>" xmlns:xsd="<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>" xmlns:soap="<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>" xmlns:wsdl="<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>" xmlns:wsp="<ulink url="http://www.w3.org/2006/07/ws-policy">http://www.w3.org/2006/07/ws-policy</ulink>">
+<wsdl:types>
+<xsd:schema xmlns:xsd="<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>" xmlns:tns="<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>" attributeFormDefault="unqualified" elementFormDefault="unqualified" targetNamespace="<ulink url="http://www.jboss.org/jbossws/ws-extensions/wsrm">http://www.jboss.org/jbossws/ws-extensions/wsrm</ulink>">
+<xsd:element name="ping" type="tns:ping"/>
+<xsd:complexType name="ping">
+<xsd:sequence/>
+</xsd:complexType>
+<xsd:element name="echo" type="tns:echo"/>
+<xsd:complexType name="echo">
+<xsd:sequence>
+<xsd:element minOccurs="0" name="arg0" type="xsd:string"/>
+</xsd:sequence>
+</xsd:complexType>
+<xsd:element name="echoResponse" type="tns:echoResponse"/>
+<xsd:complexType name="echoResponse">
+<xsd:sequence>
+<xsd:element minOccurs="0" name="return" type="xsd:string"/>
+</xsd:sequence>
+</xsd:complexType>
+</xsd:schema>
+ </wsdl:types>
+ <wsdl:message name="echoResponse">
+ <wsdl:part name="parameters" element="tns:echoResponse">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="echo">
+ <wsdl:part name="parameters" element="tns:echo">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:message name="ping">
+ <wsdl:part name="parameters" element="tns:ping">
+ </wsdl:part>
+ </wsdl:message>
+ <wsdl:portType name="SimpleService">
+ <wsdl:operation name="ping">
+ <wsdl:input name="ping" message="tns:ping">
+ </wsdl:input>
+ </wsdl:operation>
+ <wsdl:operation name="echo">
+ <wsdl:input name="echo" message="tns:echo">
+ </wsdl:input>
+ <wsdl:output name="echoResponse" message="tns:echoResponse">
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:portType>
+ <wsdl:binding name="SimpleServiceSoapBinding" type="tns:SimpleService">
+
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -->
+ <!-- Created WS-Policy with WSRM addressing assertions -->
+ <!-- - - - - - - - - - - - - - - - - - - - - - - - - - --><wsp:Policy>
+ <wswa:UsingAddressing xmlns:wswa="<ulink url="http://www.w3.org/2006/05/addressing/wsdl">http://www.w3.org/2006/05/addressing/wsdl</ulink>"/>
+ <wsrmp:RMAssertion xmlns:wsrmp="<ulink url="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">http://schemas.xmlsoap.org/ws/2005/02/rm/policy</ulink>"/>
+ </wsp:Policy>
+
+ <soap:binding style="document" transport="<ulink url="http://schemas.xmlsoap.org/soap/http">http://schemas.xmlsoap.org/soap/http</ulink>"/>
+ <wsdl:operation name="ping">
+ <soap:operation soapAction="" style="document"/>
+ <wsdl:input name="ping">
+ <soap:body use="literal"/>
+ </wsdl:input>
+ </wsdl:operation>
+ <wsdl:operation name="echo">
+ <soap:operation soapAction="" style="document"/>
+ <wsdl:input name="echo">
+ <soap:body use="literal"/>
+ </wsdl:input>
+ <wsdl:output name="echoResponse">
+ <soap:body use="literal"/>
+ </wsdl:output>
+ </wsdl:operation>
+ </wsdl:binding>
+ <wsdl:service name="SimpleService">
+ <wsdl:port name="SimpleServicePort" binding="tns:SimpleServiceSoapBinding">
+ <soap:address location="<ulink url="http://localhost:9090/hello">http://localhost:9090/hello</ulink>"/>
+ </wsdl:port>
+ </wsdl:service>
+</wsdl:definitions>
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Basic_WSRM_configuration"><title>Basic WS-RM configuration</title><para>Once the endpoint wsdl is properly updated with the policies elements, the JBossWS-CXF stack is <emphasis>automatically</emphasis> able to detect the need for the WS-Policy engine to be used, both on client and server side, for enabling WS-Reliable Messaging.</para><para>The endpoint advertises RM capabilities through the published wsdl and the client is required to also enable WS-RM for successfully exchanging messages with the server.</para><para>The regular jaxws client above is enough if the user does not need to tune any specific detail of the RM subsystem (acknowledgment / retransmission intervals, thresholds, ...)</para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Advanced_WSRM_configuration"><title>Advanced WS-RM configuration</title><para>When users want to have full control over the way WS-RM communication is established, the current CXF Bus needs to be properly configured. This can be done through a CXF Spring configuration.</para><section id="JBossWS-CXFWS-ReliableMessagingtutorial_Providing_Client_CXF_Configuration"><title>Providing Client CXF Configuration</title><para>Next step is to create the client CXF configuration file that will be used by client. The following file was copied/pasted from CXF 2.0.5 ws_rm sample. It simply activates the WSRM protocol for CXF client. We will name this file <emphasis role="bold">cxf.xml</emphasis> in our sample. Here's the content of this file:</para><screen xml:space="preserve"><beans
+ xmlns="<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xmlns:cxf="<ulink url="http://cxf.apache.org/core">http://cxf.apache.org/core</ulink>"
+ xmlns:wsa="<ulink url="http://cxf.apache.org/ws/addressing">http://cxf.apache.org/ws/addressing</ulink>"
+ xmlns:http="<ulink url="http://cxf.apache.org/transports/http/configuration">http://cxf.apache.org/transports/http/configuration</ulink>"
+ xmlns:wsrm-policy="<ulink url="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">http://schemas.xmlsoap.org/ws/2005/02/rm/policy</ulink>"
+ xmlns:wsrm-mgr="<ulink url="http://cxf.apache.org/ws/rm/manager">http://cxf.apache.org/ws/rm/manager</ulink>"
+ xsi:schemaLocation="
+ <ulink url="http://cxf.apache.org/core">http://cxf.apache.org/core</ulink>
+ <ulink url="http://cxf.apache.org/schemas/core.xsd">http://cxf.apache.org/schemas/core.xsd</ulink>
+ <ulink url="http://cxf.apache.org/transports/http/configuration">http://cxf.apache.org/transports/http/configuration</ulink>
+ <ulink url="http://cxf.apache.org/schemas/configuration/http-conf.xsd">http://cxf.apache.org/schemas/configuration/http-conf.xsd</ulink>
+ <ulink url="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">http://schemas.xmlsoap.org/ws/2005/02/rm/policy</ulink>
+ <ulink url="http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd">http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd</ulink>
+ <ulink url="http://cxf.apache.org/ws/rm/manager">http://cxf.apache.org/ws/rm/manager</ulink>
+ <ulink url="http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd">http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd</ulink>
+ <ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans.xsd">http://www.springframework.org/schema/beans/spring-beans.xsd</ulink>">
+
+ <cxf:bus>
+ <cxf:features>
+ <cxf:logging/>
+ <wsa:addressing/>
+ <wsrm-mgr:reliableMessaging>
+ <wsrm-policy:RMAssertion>
+ <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/>
+ <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/>
+ </wsrm-policy:RMAssertion>
+ <wsrm-mgr:destinationPolicy>
+ <wsrm-mgr:acksPolicy intraMessageThreshold="0" />
+ </wsrm-mgr:destinationPolicy>
+ </wsrm-mgr:reliableMessaging>
+ </cxf:features>
+ </cxf:bus>
+
+</beans>
+</screen><para>And that's almost all. The client configuration needs to picked up by the client classloader; in order to achieve that the cxf.xml file has to be put in the META-INF directory of client jar. That jar should then be provided when setting the class loader.</para><para>Alternatively the bus configuration can also be read programmatically as follows:</para><para> </para></section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Updating_Client_Code_to_Read_Bus_Configuration_File"><title>Updating Client Code to Read Bus Configuration File</title><para>And here's the last piece the updated CXF client:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.client;
+
+<emphasis role="bold">import</emphasis> java.net.URL;
+<emphasis role="bold">import</emphasis> java.io.File;
+<emphasis role="bold">import</emphasis> javax.xml.namespace.QName;
+<emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+<emphasis role="bold">import</emphasis> org.apache.cxf.Bus;
+<emphasis role="bold">import</emphasis> org.apache.cxf.BusFactory;
+<emphasis role="bold">import</emphasis> org.apache.cxf.bus.spring.SpringBusFactory;
+<emphasis role="bold">import</emphasis> org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">class</emphasis> SimpleServiceTestCase
+{
+
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">final</emphasis> String serviceURL = "http://localhost:8080/jaxws-samples-wsrm/SimpleService";
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String[] args) <emphasis role="bold">throws</emphasis> Exception
+ {
+ // create bus
+ SpringBusFactory busFactory = <emphasis role="bold">new</emphasis> SpringBusFactory();
+ URL cxfConfig = <emphasis role="bold">new</emphasis> File("resources/jaxws/samples/wsrm/cxf.xml").toURL();
+ Bus bus = busFactory.createBus(cxfConfig);
+ busFactory.setDefaultBus(bus);
+
+ // create service
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("http://www.jboss.org/jbossws/ws-extensions/wsrm", "SimpleService");
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL(serviceURL + "?wsdl");
+ Service service = Service.create(wsdlURL, serviceName);
+ SimpleService proxy = (SimpleService)service.getPort(SimpleService.class);
+
+ // invoke methods
+ proxy.ping(); // one way call
+ proxy.echo("Hello World!"); // request responce call
+
+ // shutdown bus
+ bus.shutdown(<emphasis role="bold">true</emphasis>);
+ }
+
+}
+</screen></section>
+</section>
+</section>
+<section id="JBossWS-CXFWS-ReliableMessagingtutorial_Sample_Sources"><title>Sample Sources</title><para>All sources from this tutorial are part of JBossWS-CXF distribution.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-Endpointmanagement.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-Endpointmanagement.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-Endpointmanagement.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Endpointmanagement"><title>JBossWS-Endpointmanagement</title><para>JBossWS registers MBeans that users can leverage to manage every webservice endpoint. Apart from the obvious start/stop functionalities, they provide valuable information and statistics about messages processed by the endpoints.</para><para/><para> </para><section id="JBossWS-Endpointmanagement_Getting_the_information"><title>Getting the information</title><para>JBoss ships with a JMX-Console with all the application server MBeans. It is usually available at URL <ulink url="http://localhost:8080/jmx-console">http://localhost:8080/jmx-console</ulink>. For endpoint management you might be interested in the MBeans belonging to the jboss.ws domain.</para><para>The application server also has an applet based web-console which basically has the same data as the JMX-Console plus some advanced features including snapshot graphics.</para><para>Of course!
you can access an MBean programmatically too. Please refer to the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=FAQJBossJMX">JBoss JMX faq</ulink> for further details; here is a brief code snippet you might want to start from in order to access a ManagedEndpointMBean from the same virtual machine:</para><screen xml:space="preserve"><emphasis role="bold">try</emphasis>
+{
+ MBeanServer server = MBeanServerLocator.locate();
+ ManagedEndpointMBean mep = (ManagedEndpointMBean)MBeanProxyExt.create(
+ ManagedEndpointMBean.class,
+ "jboss.ws:context=my-ctx,endpoint=MyEndpoit",
+ server);
+ ...
+}
+<emphasis role="bold">catch</emphasis> (Exception e)
+{
+ e.printStackTrace();
+}
+</screen></section>
+<section id="JBossWS-Endpointmanagement_Metrics"><title>Metrics</title><para>For each deployed endpoint you'll find an <emphasis>org.jboss.wsf.framework.management.ManagedEndpoint</emphasis> MBean providing basic start/stop functionalities and metrics. Calling a stopped endpoint will always result in a SOAP fault message.</para><para>The metrics available for each managed endpoint are:</para><itemizedlist><listitem><para> Min, max, average and total processing time: processing includes both the WS stack plus application server work and the user business logic </para></listitem><listitem><para> Last start and stop time </para></listitem><listitem><para> Request, response and fault count</para></listitem></itemizedlist></section>
+<section id="JBossWS-Endpointmanagement_Records"><title>Records</title><para>JBossWS features a highly configurable records' collection and management system. Each record is basically composed of a message plus additional information (for example the caller address and the called endpoint operation).</para><para>Endpoints can be configured with record processors that are invoked whenever a message flow is detected and records are thus created.</para><para>Every deployed endpoint is configured with default record processors. However custom processors as well as record filters can be easily plugged in and managed at any time through JMX. This gives users the chance of performing advanced analysis of the webservice traffic according to their business requirements.</para><para>Please refer to the <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Records_management">records management page</ulink> for further details.</para></section>
+<section id="JBossWS-Endpointmanagement_Snapshots_and_threshold_monitors"><title>Snapshots and threshold monitors</title><para>As previously said, the <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsole">JBoss Web Console</ulink> has interesting features including <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleSnapshots">snapshots</ulink> and <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=WebConsoleMonitoring">threshold monitors</ulink>.</para><para>Snapshots allow users to record changes of a given MBean attribute within a defined time interval. Data are sampled at a given rate and may be plotted to graphs with a few clicks. Snapshots are listed in the Web console and can be created simply browsing to <ulink url="http://localhost:8080/web-console/createSnapshot.jsp">http://localhost:8080/web-console/createSnapshot.jsp</ulink> .</para><para>Threshold monitors allow users to be notified whenever a given MBean attribute exceed a certain range!
of values. The threshold monitor's creation and management processes are similar to those mentioned above for the snapshots. Simply browse to <ulink url="http://localhost:8080/web-console/createThresholdMonitor.jsp">http://localhost:8080/web-console/createThresholdMonitor.jsp</ulink> .</para><para>Speaking of WS availability and SLA, this all becomes interesting because users can monitor and take snapshots of critical attributes like the average/max processing time of a managed endpoint. Moreover, advanced analysis can be performed leveraging ad-hoc attributes of custom <ulink url="http://jbossws.jboss.org/mediawiki/index.php?title=Endpoint_management#Re...">record processors</ulink>.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSAnnotations.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSAnnotations"><title>JBossWS-JAX-WSAnnotations</title><para/><section id="JBossWS-JAX-WSAnnotations_JAXWS_Annotations"><title>JAX-WS Annotations</title><para>For details, see <ulink url="http://www.jcp.org/en/jsr/detail?id=224">JSR-224 - Java API for XML-Based Web Services (JAX-WS) 2.0</ulink></para><para> </para><section id="JBossWS-JAX-WSAnnotations_javaxxmlwsServiceMode"><title>javax.xml.ws.ServiceMode</title><para>The ServiceMode annotation is used to specify the mode for a provider class, i.e. whether a provider wants to have access to protocol message payloads (e.g. a SOAP body) or the entire protocol messages (e.g. a SOAP envelope).</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebFault"><title>javax.xml.ws.WebFault</title><para>The WebFault annotation is used when mapping WSDL faults to Java exceptions, see section 2.5. It is used to capture the name of the fault element used when marshalling the JAXB type generated from the global element referenced by the WSDL fault message. It can also be used to customize the mapping of service specific exceptions to WSDL faults.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsRequestWrapper"><title>javax.xml.ws.RequestWrapper</title><para>The RequestWrapper annotation is applied to the methods of an SEI. It is used to capture the JAXB generated request wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. The default value of localName element is the operationName as defined in WebMethod annotation and the default value for the targetNamespace element is the target namespace of the SEI.When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsResponseWrapper"><title>javax.xml.ws.ResponseWrapper</title><para>The ResponseWrapper annotation is applied to the methods of an SEI. It is used to capture the JAXB generated response wrapper bean and the element name and namespace for marshalling / unmarshalling the bean. The default value of the localName element is the operationName as defined in the WebMethod appended with ”Response” and the default value of the targetNamespace element is the target namespace of the SEI. When starting from Java, this annotation is used to resolve overloading conflicts in document literal mode. Only the className element is required in this case.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceClient"><title>javax.xml.ws.WebServiceClient</title><para>The WebServiceClient annotation is specified on a generated service class (see 2.7). It is used to associate a class with a specific Web service, identify by a URL to a WSDL document and the qualified name of a wsdl:service element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebEndpoint"><title>javax.xml.ws.WebEndpoint</title><para>The WebEndpoint annotation is specified on the getPortName() methods of a generated service class (see 2.7). It is used to associate a get method with a specific wsdl:port, identified by its local name (a NCName).</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceProvider"><title>javax.xml.ws.WebServiceProvider</title><para>The WebServiceProvider annotation is specified on classes that implement a strongly typed javax- .xml.ws.Provider. It is used to declare that a class that satisfies the requirements for a provider (see 5.1) does indeed define a Web service endpoint, much like the WebService annotation does for SEI-based endpoints.</para><para>The WebServiceProvider and WebService annotations are mutually exclusive.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsBindingType"><title>javax.xml.ws.BindingType</title><para>The BindingType annotation is applied to an endpoint implementation class. It specifies the binding to use when publishing an endpoint of this type.</para><para>The default binding for an endpoint is the SOAP 1.1/HTTP one</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRef"><title>javax.xml.ws.WebServiceRef</title><para>The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250 [32]. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform, where it is subject to the common resource injection rules described by the platform specification [33].</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsWebServiceRefs"><title>javax.xml.ws.WebServiceRefs</title><para>The WebServiceRefs annotation is used to declare multiple references to Web services on a single class. It is necessary to work around the limition against specifying repeated annotations of the same type on any given class, which prevents listing multiple javax.ws.WebServiceRef annotations one after the other. This annotation follows the resource pattern exemplified by the javax.annotation.Resources annotation in JSR-250.</para><para>Since no name and type can be inferred in this case, each WebServiceRef annotation inside a WebServiceRefs MUST contain name and type elements with non-default values. The WebServiceRef annotation is required to be honored when running on the Java EE 5 platform, where it is subject to the common resource injection rules described by the platform specification.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsAction"><title>javax.xml.ws.Action</title><para>The Action annotation is applied to the methods of a SEI. It used to generate the wsa:Action on wsdl:input and wsdl:output of each wsdl:operation mapped from the annotated methods.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxxmlwsFaultAction"><title>javax.xml.ws.FaultAction</title><para>The FaultAction annotation is used within the Action annotation to generate the wsa:Action element on the wsdl:fault element of each wsdl:operation mapped from the annotated methods.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_Annotations_Defined_by_JSR181"><title>Annotations Defined by JSR-181</title><para>JSR-181 defines the syntax and semantics of Java Web Service (JWS) metadata and default values.</para><para>For details, see <ulink url="http://jcp.org/en/jsr/detail?id=181">JSR 181 - Web Services Metadata for the Java Platform</ulink></para><para> </para><section id="JBossWS-JAX-WSAnnotations_javaxjwsWebService"><title>javax.jws.WebService</title><para>Marks a Java class as implementing a Web Service, or a Java interface as defining a Web Service interface.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebMethod"><title>javax.jws.WebMethod</title><para>Customizes a method that is exposed as a Web Service operation.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsOneWay"><title>javax.jws.OneWay</title><para>Indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method. A JSR-181 processor is REQUIRED to report an error if an operation marked @Oneway has a return value, declares any checked exceptions or has any INOUT or OUT parameters.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebParam"><title>javax.jws.WebParam</title><para>Customizes the mapping of an individual parameter to a Web Service message part and XML element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsWebResult"><title>javax.jws.WebResult</title><para>Customizes the mapping of the return value to a WSDL part and XML element.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsSOAPBinding"><title>javax.jws.SOAPBinding</title><para>Specifies the mapping of the Web Service onto the SOAP message protocol.</para><para>The SOAPBinding annotation has a target of TYPE and METHOD. The annotation may be placed on a method if and only if the SOAPBinding.style is DOCUMENT. Implementations MUST report an error if the SOAPBinding annotation is placed on a method with a SOAPBinding.style of RPC. Methods that do not have a SOAPBinding annotation accept the SOAPBinding behavior defined on the type.</para><para> </para></section>
+<section id="JBossWS-JAX-WSAnnotations_javaxjwsHandlerChain"><title>javax.jws.HandlerChain</title><para>The @HandlerChain annotation associates the Web Service with an externally defined handler chain.</para><para>It is an error to combine this annotation with the @SOAPMessageHandlers annotation.</para><para>The @HandlerChain annotation MAY be present on the endpoint interface and service implementation bean. The service implementation bean's @HandlerChain is used if @HandlerChain is present on both.</para><para>The @HandlerChain annotation MAY be specified on the type only. The annotation target includes METHOD and FIELD for use by JAX-WS-2.0.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSTools.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSTools.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-JAX-WSTools.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-JAX-WSTools"><title>JBossWS-JAX-WSTools</title><para>The JAX-WS tools provided by JBossWS can be used in a variety of ways. First we will look at server-side development strategies, and then proceed to the client.</para><para/><section id="JBossWS-JAX-WSTools_Server_side"><title>Server side</title><para>When developing a Web Service Endpoint (the server-side) you have the option of starting from Java (bottom-up development), or from the abstact contract (WSDL) that defines your service (top-down development). If this is a new service (no existing contract), the bottom-up approach is the fastest route; you only need to add a few annotations to your classes to get a service up and running. However, if you are developing a service with an already defined contract, it is far simpler to use the top-down approach, since the provided tool will generate the annotated code for you.</para><para>Bottom-up use cases:</para!
><itemizedlist><listitem><para> Exposing an already existing EJB3 bean as a Web Service </para></listitem><listitem><para> Providing a new service, and you want the contract to be generated for you </para></listitem></itemizedlist><para>Top-down use cases:</para><itemizedlist><listitem><para> Replacing the implementation of an existing Web Service, and you can't break compatibility with older clients </para></listitem><listitem><para> Exposing a service that conforms to a contract specified by a third party (e.g. a vender that calls you back using an already defined protocol). </para></listitem><listitem><para> Creating a service that adheres to the XML Schema and WSDL you developed by hand up front </para></listitem></itemizedlist><para>The following JAX-WS command line tools are included in JBossWS:</para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> Command </entry><entry> Description </entry><!
/row></thead><tbody><row><entry><para><link linkend="chap_JBos!
sWS-wspr
ovide">JBossWS - wsprovide</link></para></entry><entry>Generates JAX-WS portable artifacts, and provides the abstract contract. Used for bottom-up development.</entry></row><row><entry><para><link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link></para></entry><entry>Consumes the abstract contract (WSDL and Schema files), and produces artifacts for both a server and client. Used for top-down and client development</entry></row><row><entry><para><link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link></para></entry><entry>Executes a Java client (has a main method) using the JBossWS classpath.</entry></row></tbody></tgroup></informaltable><section id="JBossWS-JAX-WSTools_BottomUp_Using_wsprovide"><title>Bottom-Up (Using wsprovide)</title><para>The bottom-up strategy involves developing the Java code for your service, and then annotating it using JAX-WS annotations. These annotations can be used to customize the contract that is generated for your service!
. For example, you can change the operation name to map to anything you like. However, all of the annotations have sensible defaults, so only the @WebService annotation is required.</para><para>This can be as simple as creating a single class:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ <emphasis role="bold">return</emphasis> input;
+ }
+}
+</screen><para>A JSE or EJB3 deployment can be built using this class, and it is the only Java code needed to deploy on JBossWS. The WSDL, and all other Java artifacts called "wrapper classes" will be generated for you at deploy time. This actually goes beyond the JAX-WS specification, which requires that wrapper classes be generated using an offline tool. The reason for this requirement is purely a vender implementation problem, and since we do not believe in burdening a developer with a bunch of additional steps, we generate these as well. However, if you want your deployment to be portable to other application servers, you will unfortunately need to use a tool and add the generated classes to your deployment.</para><para>This is the primary purpose of the <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>tool, to generate portable JAX-WS artifacts. Additionally, it can be used to "provide" the abstract contract (WSDL file) for your service. This can be obt!
ained by invoking <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link> using the "-w" option:</para><screen xml:space="preserve">$ javac -d . -classpath jboss-jaxws.jar Echo.java
+$ wsprovide -w echo.Echo
+Generating WSDL:
+EchoService.wsdl
+Writing Classes:
+echo/jaxws/Echo.class
+echo/jaxws/EchoResponse.class
+</screen><para>Inspecting the WSDL reveals a service called EchoService:</para><screen xml:space="preserve"><service name='EchoService'><port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/></port>
+</service>
+</screen><para>As expected, this service defines one operation, "echo":</para><screen xml:space="preserve"><portType name='Echo'><operation name='echo' parameterOrder='echo'>
+ <input message='tns:Echo_echo'/>
+ <output message='tns:Echo_echoResponse'/></operation>
+</portType>
+</screen><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>Remember that <emphasis role="bold">when deploying on JBossWS you do not need to run this tool.</emphasis> You only need it for generating portable artifacts and/or the abstract contract for your service.</emphasis></para></para></note><para>Let's create a POJO endpoint for deployment on JBoss AS. A simple web.xml needs to be created:</para><screen xml:space="preserve"><web-app xmlns="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink>"
+ xmlns:xsi="<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>"
+ xsi:schemaLocation="<ulink url="http://java.sun.com/xml/ns/j2ee">http://java.sun.com/xml/ns/j2ee</ulink> <ulink url="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd</ulink>"
+ version="2.4">
+
+ <servlet>
+ <servlet-name>Echo</servlet-name>
+ <servlet-class>echo.Echo</servlet-class>
+ </servlet>
+
+ <servlet-mapping>
+ <servlet-name>Echo</servlet-name>
+ <url-pattern>/Echo</url-pattern>
+ </servlet-mapping>
+</web-app>
+</screen><para>The web.xml and the single class can now be used to create a war:</para><screen xml:space="preserve">$ mkdir -p WEB-INF/classes
+$ cp -rp echo WEB-INF/classes/
+$ cp web.xml WEB-INF
+$ jar cvf echo.war WEB-INF
+added manifest
+adding: WEB-INF/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/(in = 0) (out= 0)(stored 0%)
+adding: WEB-INF/classes/echo/Echo.class(in = 340) (out= 247)(deflated 27%)
+adding: WEB-INF/web.xml(in = 576) (out= 271)(deflated 52%)
+</screen><para>The war can then be deployed:</para><screen xml:space="preserve">cp echo.war /usr/local/jboss-4.2.0.GA-ejb3/server/default/deploy
+</screen><para>This will internally invoke <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>, which will generate the WSDL. If deployment was successful, and you are using the default settings, it should be available here: <ulink url="http://localhost:8080/echo/Echo?wsdl">http://localhost:8080/echo/Echo?wsdl</ulink></para><para>For a portable JAX-WS deployment, the wrapper classes generated earlier could be added to the deployment.</para></section>
+<section id="JBossWS-JAX-WSTools_TopDown_Using_wsconsume"><title>Top-Down (Using wsconsume)</title><para>The top-down development strategy begins with the abstract contract for the service, which includes the WSDL file and zero or more schema files. The <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> tool is then used to consume this contract, and produce annotated Java classes (and optionally sources) that define it.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>wsconsume seems to have a problem with symlinks on unix systems</para></para></note><para>Using the WSDL file from the bottom-up example, a new Java implementation that adheres to this service can be generated. The "-k" option is passed to <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> to preserve the Java source files that are generated, instead of providing just classes:</para><screen xml:space="preserve">
+$ wsconsume -k EchoService.wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</screen><para>The following table shows the purpose of each generated file:</para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> File </entry><entry> Purpose </entry></row></thead><tbody><row><entry>Echo.java</entry><entry>Service Endpoint Interface</entry></row><row><entry>Echo_Type.java</entry><entry>Wrapper bean for request message</entry></row><row><entry>EchoResponse.java</entry><entry>Wrapper bean for response message</entry></row><row><entry>ObjectFactory.java</entry><entry>JAXB XML Registry</entry></row><row><entry>package-info.java</entry><entry>Holder for JAXB package annotations</entry></row><row><entry>EchoService.java</entry><entry>Used only by JAX-WS clients</entry></row></tbody></tgroup></informaltable><para>Examining the Service Endpoint Interface reveals annotations that are more explicit than in the class written by hand in the bottom-up example, however, these evaluate to the sa!
me contract:</para><screen xml:space="preserve">@WebService(name = "Echo", targetNamespace = "http://echo/")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">interface</emphasis> Echo {
+ @WebMethod
+ @WebResult(targetNamespace = "")
+ @RequestWrapper(localName = "echo", targetNamespace = "http://echo/", className = "echo.Echo_Type")
+ @ResponseWrapper(localName = "echoResponse", targetNamespace = "http://echo/", className = "echo.EchoResponse")
+ <emphasis role="bold">public</emphasis> String echo(
+ @WebParam(name = "arg0", targetNamespace = "")
+ String arg0);
+
+}
+</screen><para>The only missing piece (besides the packaging) is the implementation class, which can now be written, using the above interface.</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> echo;
+
+(a)javax.jws.WebService(endpointInterface="echo.Echo")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoImpl <emphasis role="bold">implements</emphasis> Echo
+{
+ <emphasis role="bold">public</emphasis> String echo(String arg0)
+ {
+ <emphasis role="bold">return</emphasis> arg0;
+ }
+}
+</screen></section>
+</section>
+<section id="JBossWS-JAX-WSTools_Client_Side"><title>Client Side</title><para>Before going to detail on the client-side it is important to understand the decoupling concept that is central to Web Services. Web Services are not the best fit for internal RPC, even though they can be used in this way. There are much better technologies for this (CORBA, and RMI for example). Web Services were designed specifically for interoperable coarse-grained correspondence. There is no expectation or guarantee that any party participating in a Web Service interaction will be at any particular location, running on any particular OS, or written in any particular programming language. So because of this, it is important to clearly separate client and server implementations. The only thing they should have in common is the abstract contract definition. If, for whatever reason, your software does not adhere to this principal, then you should not be using Web Services. For the above reasons, the!
<emphasis><emphasis role="bold">recommended methodology for developing a client is</emphasis></emphasis> to follow <emphasis><emphasis role="bold">the top-down approach</emphasis></emphasis>, even if the client is running on the same server.</para><para>Let's repeat the process of the top-down section, although using the deployed WSDL, instead of the one generated offline by <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link>. The reason why we do this is just to get the right value for soap:address. This value must be computed at deploy time, since it is based on container configuration specifics. You could of course edit the WSDL file yourself, although you need to ensure that the path is correct.</para><para>Offline version:</para><screen xml:space="preserve"><service name='EchoService'>
+ <port binding='tns:EchoBinding' name='EchoPort'>
+ <soap:address location='REPLACE_WITH_ACTUAL_URL'/>
+ </port></service>
+</screen><para>Online version:</para><screen xml:space="preserve"><service name="EchoService">
+ <port binding="tns:EchoBinding" name="EchoPort">
+ <soap:address location="<ulink url="http://localhost.localdomain:8080/echo/Echo">http://localhost.localdomain:8080/echo/Echo</ulink>"/>
+ </port>
+</service>
+</screen><para>Using the online deployed version with <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link>:</para><screen xml:space="preserve">$ wsconsume -k http://localhost:8080/echo/Echo?wsdl
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+echo/Echo.java
+echo/EchoResponse.java
+echo/EchoService.java
+echo/Echo_Type.java
+echo/ObjectFactory.java
+echo/package-info.java
+</screen><para>The one class that was not examined in the top-down section, was EchoService.java. Notice how it stores the location the WSDL was obtained from.</para><screen xml:space="preserve">@WebServiceClient(name = "EchoService", targetNamespace = "http://echo/", wsdlLocation = "http://localhost:8080/echo/Echo?wsdl")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoService <emphasis role="bold">extends</emphasis> Service
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">final</emphasis> <emphasis role="bold">static</emphasis> URL ECHOSERVICE_WSDL_LOCATION;
+
+ <emphasis role="bold">static</emphasis> {
+ URL url = <emphasis role="bold">null</emphasis>;
+ <emphasis role="bold">try</emphasis> {
+ url = <emphasis role="bold">new</emphasis> URL("http://localhost:8080/echo/Echo?wsdl");
+ } <emphasis role="bold">catch</emphasis> (MalformedURLException e) {
+ e.printStackTrace();
+ }
+ ECHOSERVICE_WSDL_LOCATION = url;
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService(URL wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ <emphasis role="bold">public</emphasis> EchoService() {
+ <emphasis role="bold">super</emphasis>(ECHOSERVICE_WSDL_LOCATION, <emphasis role="bold">new</emphasis> QName("http://echo/", "EchoService"));
+ }
+
+ @WebEndpoint(name = "EchoPort")
+ <emphasis role="bold">public</emphasis> Echo getEchoPort() {
+ <emphasis role="bold">return</emphasis> (Echo)super.getPort(<emphasis role="bold">new</emphasis> QName("http://echo/", "EchoPort"), Echo.class);
+ }
+}
+</screen><para>As you can see, this generated class extends the main client entry point in JAX-WS, javax.xml.ws.Service. While you can use Service directly, this is far simpler since it provides the configuration info for you. The only method we really care about is the getEchoPort() method, which returns an instance of our Service Endpoint Interface. Any WS operation can then be called by just invoking a method on the returned interface.</para><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>It's not recommended to refer to a remote WSDL URL in a production application. This causes network I/O every time you instantiate the Service Object. Instead, use the tool on a saved local copy, or use the URL version of the constructor to provide a new WSDL location.</emphasis></para></para></note><para>All that is left to do, is write and compile the client:</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> e!
cho.*;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EchoClient
+{
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">static</emphasis> <emphasis role="bold">void</emphasis> main(String args[])
+ {
+ <emphasis role="bold">if</emphasis> (args.length != 1)
+ {
+ System.err.println("usage: EchoClient <message>");
+ System.exit(1);
+ }
+
+ EchoService service = <emphasis role="bold">new</emphasis> EchoService();
+ Echo echo = service.getEchoPort();
+ System.out.println("Server said: " + echo.echo(args[0]));
+ }}
+</screen><para>It can then be easily executed using the <link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link> tool. This is just a convenience tool that invokes java with the needed classpath:</para><screen xml:space="preserve">$ wsrunclient EchoClient 'Hello World!'
+Server said: Hello World!
+</screen><para>It is easy to change the endpoint address of your operation at runtime, setting the ENDPOINT_ADDRESS_PROPERTY as shown below:</para><screen xml:space="preserve">...
+ EchoService service = <emphasis role="bold">new</emphasis> EchoService();
+ Echo echo = service.getEchoPort();
+
+ /* Set NEW Endpoint Location */
+ String endpointURL = "http://NEW_ENDPOINT_URL";
+ BindingProvider bp = (BindingProvider)echo;
+ bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointURL);
+
+ System.out.println("Server said: " + echo.echo(args[0]));
+...
+</screen></section>
+<section id="JBossWS-JAX-WSTools_Commandline_Maven_Plugin_and_Ant_Task_Reference"><title>Command-line, Maven Plugin and Ant Task Reference</title><itemizedlist><listitem><para> <link linkend="chap_JBossWS-wsconsume">JBossWS - wsconsume</link> reference page </para></listitem><listitem><para> <link linkend="chap_JBossWS-wsprovide">JBossWS - wsprovide</link> reference page </para></listitem><listitem><para> <link linkend="chap_JBossWS-wsrunclient">JBossWS - wsrunclient</link> reference page</para></listitem></itemizedlist></section>
+<section id="JBossWS-JAX-WSTools_JAXWS_binding_customization"><title>JAX-WS binding customization</title><para>An introduction to binding customizations:</para><itemizedlist><listitem><para> <ulink url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html">http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html</ulink> </para></listitem><listitem><para> <ulink url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...">binding schema</ulink> </para></listitem><listitem><para> <ulink url="https://jax-ws.dev.java.net/nonav/guide/customizations/">xnsdoc</ulink> </para></listitem></itemizedlist><para>The schema for the binding customization files can be found here:</para><itemizedlist><listitem><para> <ulink url="https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...">https://jax-ws.dev.java.net/source/browse/jax-ws/guide/docs/wsdl-customiz...!
2&view=log</ulink> </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-QuickStart.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-QuickStart.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-QuickStart.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,193 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-QuickStart"><title>JBossWS-QuickStart</title><para/><para> </para><section id="JBossWS-QuickStart_Right_on"><title>Right on'</title><para>JBossWS uses the JBoss application server as its target container. The following examples focus on web service deployments that leverage EJB3 service implementations and the JAX-WS programming models. For further information on POJO service implementations and advanced topics you need consult the user guide.</para><para>In the following sections we will explore the samples that ship with the JBossWS distribution. They provide a build structure based on Ant to get you started quickly.</para></section>
+<section id="JBossWS-QuickStart_Developing_web_service_implementations"><title>Developing web service implementations</title><para>JAX-WS does leverage <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html">JDK 5 annotations</ulink> in order to express web service meta data on Java components and to describe the mapping between Java data types and XML. When developing web service implementations you need to decide whether you are going start with an abstract contract (<ulink url="http://www.w3.org/TR/wsdl">WSDL</ulink>) or a Java component.</para><para>If you are in charge to provide the service implementation, then you are probably going to start with the implementation and derive the abstract contract from it. You are probably not even getting in touch with the WSDL unless you hand it to 3rd party clients. For this reason we are going to look at a service implementation that leverages <ulink url="http://jcp.org/en/jsr/detail?id=181">JSR-181 annot!
ations</ulink>.</para><note><para><para><emphasis role="bold">Note</emphasis></para><para>Even though detailed knowledge of web service meta data is not required, it will definitely help if you make yourself familiar with it. For further information see</para><itemizedlist><listitem><para> <ulink url="http://jcp.org/en/jsr/detail?id=181">Web service meta data (JSR-181)</ulink> </para></listitem><listitem><para> <ulink url="http://java.sun.com/webservices/jaxb/">Java API for XML binding (JAXB)</ulink></para></listitem></itemizedlist></para></note><para>When starting from Java you must provide the service implementation. A valid endpoint implementation class must meet the following requirements:</para><itemizedlist><listitem><para> It <emphasis>must</emphasis> carry a <computeroutput>javax.jws.WebService</computeroutput> annotation (see JSR 181) </para></listitem><listitem><para> All method parameters and return types <emphasis>must</emphasis> be compatible with the JAXB !
2.0 </para></listitem></itemizedlist><para>Let's look at a sam!
ple EJB3
component that is going to be exposed as a web service. (This is based on the Retail example).</para><para>Don't be confused with the EJB3 annotation <computeroutput>@Stateless</computeroutput>. We concentrate on the <computeroutput>@WebService</computeroutput> annotation for now.</para><para><emphasis role="bold">The service implementation class</emphasis></para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis> javax.ejb.Stateless;
+<emphasis role="bold">import</emphasis> javax.jws.WebService;
+<emphasis role="bold">import</emphasis> javax.jws.WebMethod;
+<emphasis role="bold">import</emphasis> javax.jws.soap.SOAPBinding;
+
+@Stateless (1)
+@WebService( (2)
+ name="ProfileMgmt",
+ targetNamespace = "http://org.jboss.ws/samples/retail/profile",
+ serviceName = "ProfileMgmtService")
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE) (3)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ProfileMgmtBean {
+
+ @WebMethod (4)
+ <emphasis role="bold">public</emphasis> DiscountResponse getCustomerDiscount(DiscountRequest request) {
+ <emphasis role="bold">return</emphasis> <emphasis role="bold">new</emphasis> DiscountResponse(request.getCustomer(), 10.00);
+ }
+}
+
+</screen><orderedlist><listitem><para> We are using a stateless session bean implementation </para></listitem><listitem><para> Exposed a web service with an explicit namespace </para></listitem><listitem><para> It's a doc/lit bare endpoint </para></listitem><listitem><para> And offers an 'getCustomerDiscount' operation </para></listitem></orderedlist><para> <emphasis role="bold"> What about the payload? </emphasis></para><para>The method parameters and return values are going to represent our XML payload and thus require being compatible with <ulink url="http://java.sun.com/webservices/jaxb/">JAXB2</ulink>. Actually you wouldn't need any JAXB annotations for this particular example, because JAXB relies on meaningful defaults. For the sake of documentation we put the more important ones here.</para><para>Take a look at the request parameter:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.retail.profile;
+
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlAccessType;
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlAccessorType;
+<emphasis role="bold">import</emphasis> javax.xml.bind.annotation.XmlType;
+
+<emphasis role="bold">import</emphasis> org.jboss.test.ws.jaxws.samples.retail.Customer;
+
+(a)XmlAccessorType(XmlAccessType.field)
+@XmlType( (1)
+ name = "discountRequest",
+ namespace="http://org.jboss.ws/samples/retail/profile",
+ propOrder = { "customer" }
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DiscountRequest {
+
+ <emphasis role="bold">protected</emphasis> Customer customer;
+
+ <emphasis role="bold">public</emphasis> DiscountRequest() {
+ }
+
+ <emphasis role="bold">public</emphasis> DiscountRequest(Customer customer) {
+ this.customer = customer;
+ }
+
+ <emphasis role="bold">public</emphasis> Customer getCustomer() {
+ <emphasis role="bold">return</emphasis> customer;
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setCustomer(Customer value) {
+ this.customer = value;
+ }
+
+}
+
+</screen><orderedlist><listitem><para>In this case we use <computeroutput>@XmlType</computeroutput> to specify an XML complex type name and override the namespace. </para></listitem></orderedlist><para> </para><variablelist/><section id="JBossWS-QuickStart_Deploying_service_implementations"><title>Deploying service implementations</title><para>Service deployment basically depends on the implementation type. As you may already know web services can be implemented as EJB3 components or plain old Java objects. This quick start leverages EJB3 components in all examples, thats why we are going to look at this case in the next sections.</para><para> </para><para><emphasis role="bold"> EJB3 services </emphasis></para><para>Simply wrap up the service implementation class, the endpoint interface and any custom data types in a JAR and drop them in the <computeroutput>deploy</computeroutput> directory. No additional deployment descriptors required. Any meta data required for the dep!
loyment of the actual web service is taken from the annotations provided on the implementation class and the service endpoint interface. JBossWS will intercept that EJB3 deployment (the bean will also be there) and create an HTTP endpoint at deploy-time:</para><para> </para><para><emphasis role="bold">The JAR package structure</emphasis></para><screen xml:space="preserve">jar -tf jaxws-samples-retail.jar
+
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.class
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtBean.class
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.class
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.class
+</screen><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>If the deployment was successful you should be able to see your endpoint at <ulink url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink></emphasis></para><para> </para></para></note></section>
+</section>
+<section id="JBossWS-QuickStart_Consuming_web_services"><title>Consuming web services</title><para>When creating web service clients you would usually start from the WSDL. JBossWS ships with a set of tools to generate the required JAX-WS artefacts to build client implementations. In the following section we will look at the most basic usage patterns. For a more detailed introductoin to web service client please consult the <ulink url="http://community.jboss.org/docs/DOC-13972">user guide</ulink>.</para><para> </para><para> </para><para><emphasis role="bold">Using wsconsume </emphasis></para><para> </para><para>The <link linkend="chap_JBossWS-wsconsume">wsconsume tool</link> is used to consume the abstract contract (WSDL) and produce annotated Java classes (and optionally sources) that define it. We are going to start with the WSDL from our retail example (<link linkend="JBossWS-QuickStart_Profile_MgmtService">ProfileMgmtService.wsdl</link>). For a detailed tool reference!
you need to consult the user guide.</para><screen xml:space="preserve">wsconsume is a command line tool that generates
+portable JAX-WS artifacts from a WSDL file.
+
+usage: org.jboss.ws.tools.jaxws.command.wsconsume [options] <wsdl-url>
+
+options:
+ -h, --help Show this help message
+ -b, --binding=<file> One or more JAX-WS or JAXB binding files
+ -k, --keep Keep/Generate Java source
+ -c --catalog=<file> Oasis XML Catalog file for entity resolution
+ -p --package=<name> The target package for generated source
+ -w --wsdlLocation=<loc> Value to use for @WebService.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces
+</screen><para>Let's try it on our retail sample:</para><screen xml:space="preserve">~./wsconsume.sh -k
+-p org.jboss.test.ws.jaxws.samples.retail.profile ProfileMgmtService.wsdl (1)
+
+org/jboss/test/ws/jaxws/samples/retail/profile/Customer.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountRequest.java
+org/jboss/test/ws/jaxws/samples/retail/profile/DiscountResponse.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ObjectFactory.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmt.java
+org/jboss/test/ws/jaxws/samples/retail/profile/ProfileMgmtService.java
+org/jboss/test/ws/jaxws/samples/retail/profile/package-info.java
+
+</screen><orderedlist><listitem><para> As you can see we did use the <computeroutput>-p</computeroutput> switch to specify the package name of the generated sources. </para></listitem></orderedlist><para> </para><para><emphasis role="bold"> The generated artifacts explained </emphasis></para><informaltable><tgroup cols="2"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><thead><row><entry> File </entry><entry> Purpose </entry></row></thead><tbody><row><entry>ProfileMgmt.java</entry><entry>Service Endpoint Interface</entry></row><row><entry>Customer.java</entry><entry>Custom data type</entry></row><row><entry>Discount*.java</entry><entry>Custom data type</entry></row><row><entry>ObjectFactory.java</entry><entry>JAXB XML Registry</entry></row><row><entry>package-info.java</entry><entry>Holder for JAXB package annotations</entry></row><row><entry>ProfileMgmtService.java</entry><entry>Service factory</entry></row></tbody></tgroup></informaltable><para>B!
asically <computeroutput>wsconsume</computeroutput> generates all custom data types (JAXB annotated classes), the service endpoint interface and a service factory class. We will look at how these artifacts can be used the build web service client implementations in the next section.</para><para> </para><bridgehead id="Constructing_a_service_stub">Constructing a service stub</bridgehead><para>Web service clients make use of a service stubs that hide the details of a remote web service invocation. To a client application a WS invocation just looks like an invocation of any other business component. In this case the service endpoint interface acts as the business interface. JAX-WS does use a service factory class to construct this as particular service stub:</para><screen xml:space="preserve"><emphasis role="bold">import</emphasis> javax.xml.ws.Service;
+
+Service service = Service.create( (1)
+ <emphasis role="bold">new</emphasis> URL("http://example.org/service?wsdl"),
+ <emphasis role="bold">new</emphasis> QName("MyService")
+);
+ProfileMgmt profileMgmt = service.getPort(ProfileMgmt.class); (2)
+
+// do something with the service stub here... (3)
+</screen><orderedlist><listitem><para> Create a service factory using the WSDL location and the service name </para></listitem><listitem><para> Use the tool created service endpoint interface to build the service stub </para></listitem><listitem><para> Use the stub like any other business interface </para></listitem></orderedlist><para> </para><para> </para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><note><para><para><emphasis>The creation of the service stub is quite costly. You should take care that it gets reused by your application code (However <emphasis role="bold">it's not thread safe</emphasis>). Within a EE5 environment you might want to investigate the <computeroutput>@WebServiceRef</computeroutput> functionality.</emphasis></para><para> </para></para></note></section>
+<section id="JBossWS-QuickStart_Appendix"><title>Appendix</title><section id="JBossWS-QuickStart_Profile_MgmtService"><title>ProfileMgmtService.wsdl</title><screen xml:space="preserve"><definitions
+ name='ProfileMgmtService'
+ targetNamespace='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns='<ulink url="http://schemas.xmlsoap.org/wsdl/">http://schemas.xmlsoap.org/wsdl/</ulink>'
+ xmlns:ns1='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:soap='<ulink url="http://schemas.xmlsoap.org/wsdl/soap/">http://schemas.xmlsoap.org/wsdl/soap/</ulink>'
+ xmlns:tns='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xsd='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+
+ <types>
+
+ <xs:schema targetNamespace='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ version='1.0' xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+ <xs:complexType name='customer'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='creditCardDetails' type='xs:string'/>
+ <xs:element minOccurs='0' name='firstName' type='xs:string'/>
+ <xs:element minOccurs='0' name='lastName' type='xs:string'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema>
+
+ <xs:schema
+ targetNamespace='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ version='1.0'
+ xmlns:ns1='<ulink url="http://org.jboss.ws/samples/retail">http://org.jboss.ws/samples/retail</ulink>'
+ xmlns:tns='<ulink url="http://org.jboss.ws/samples/retail/profile">http://org.jboss.ws/samples/retail/profile</ulink>'
+ xmlns:xs='<ulink url="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</ulink>'>
+
+ <xs:import namespace='<ulink url="http://org.jboss.ws/samples/retail'/">http://org.jboss.ws/samples/retail'/</ulink>>
+ <xs:element name='getCustomerDiscount'
+ nillable='true' type='tns:discountRequest'/>
+ <xs:element name='getCustomerDiscountResponse'
+ nillable='true' type='tns:discountResponse'/>
+ <xs:complexType name='discountRequest'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='customer' type='ns1:customer'/>
+
+ </xs:sequence>
+ </xs:complexType>
+ <xs:complexType name='discountResponse'>
+ <xs:sequence>
+ <xs:element minOccurs='0' name='customer' type='ns1:customer'/>
+ <xs:element name='discount' type='xs:double'/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:schema>
+
+ </types>
+
+ <message name='ProfileMgmt_getCustomerDiscount'>
+ <part element='tns:getCustomerDiscount' name='getCustomerDiscount'/>
+ </message>
+ <message name='ProfileMgmt_getCustomerDiscountResponse'>
+ <part element='tns:getCustomerDiscountResponse'
+ name='getCustomerDiscountResponse'/>
+ </message>
+ <portType name='ProfileMgmt'>
+ <operation name='getCustomerDiscount'
+ parameterOrder='getCustomerDiscount'>
+
+ <input message='tns:ProfileMgmt_getCustomerDiscount'/>
+ <output message='tns:ProfileMgmt_getCustomerDiscountResponse'/>
+ </operation>
+ </portType>
+ <binding name='ProfileMgmtBinding' type='tns:ProfileMgmt'>
+ <soap:binding style='document'
+ transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='getCustomerDiscount'>
+ <soap:operation soapAction=''/>
+ <input>
+
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation>
+ </binding>
+ <service name='ProfileMgmtService'>
+ <port binding='tns:ProfileMgmtBinding' name='ProfileMgmtPort'>
+
+ <soap:address
+ location='<ulink url="http://">http://</ulink><HOST>:<PORT>/jaxws-samples-retail/ProfileMgmtBean'/>
+ </port>
+ </service>
+</definitions></screen><para> </para> </section>
+</section></chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-Recordsmanagement.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-Recordsmanagement.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-Recordsmanagement.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Recordsmanagement"><title>JBossWS-Recordsmanagement</title><para>JBossWS records' collection and management system gives administrators a means of performing custom analysis of their webservice traffic as well as exporting communication logs.</para><para/><para> </para><section id="JBossWS-Recordsmanagement_What_is_recorded"><title>What is recorded</title><para>Each record is basically composed of a message plus additional information; here are the current record attributes:</para><itemizedlist><listitem><para> Creation date </para></listitem><listitem><para> Source host </para></listitem><listitem><para> Destination host </para></listitem><listitem><para> Message type (in/out) </para></listitem><listitem><para> Invoked endpoint operation </para></listitem><listitem><para> Message envelope (including both soap:header and soap:body for SOAP messages) </para></listitem><listitem><para> Http headers </para></list!
item><listitem><para> Record group ID (allowing records belonging to the same message flow to be linked together) </para></listitem></itemizedlist><para>Of course records may also have meaningful values for a subset of the afore mentioned record attributes.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Use_cases"><title>Use cases</title><para>What are records useful for? In spite of <link linkend="chap_JBossWS-Endpointmanagement">endpoint metrics</link> that provide response time information and counts of invocations, records provide users with rich data about the content of the exchanged messages and their sender/receiver. The record system allows fine grained management and is customizable according to the users need; some of the use cases supported by the default configuration are:</para><itemizedlist><listitem><para> Logging request and response messages: being able to record messages received from and sent to a given service consumer without stopping the provider may be really useful. You just need to set the <emphasis>recording</emphasis> attribute of their endpoint's LogRecorder to true. The added value of this logging solution comes from the use of filters through which messages coming from a given address and related to a gi!
ven wsdl operation only can be logged. </para></listitem><listitem><para> Accountability: service providers may want to know which consumers are actually hitting a given service. This can be done for example using the <emphasis>getClientHosts</emphasis> functionality of the MemoryBufferRecorder once it has been switched to recording state. </para></listitem><listitem><para> Getting statistics, filtering records: service administrators might want to see the last records related to a given endpoint or operation, the last records related to messages coming from a given customer and the response the system gave them, etc. These information can be obtained using the <emphasis>getRecordsByOperation</emphasis>, <emphasis>getRecordsByClientHost</emphasis> or the more general <emphasis>getMatchingRecords</emphasis> functionality of the MemoryBufferRecorder.</para></listitem></itemizedlist><para> </para></section>
+<section id="JBossWS-Recordsmanagement_How_it_works_and_how_to_use_it"><title>How it works and how to use it</title><para>The recording system is composed of</para><itemizedlist><listitem><para> JAX-WS handlers intercepting inbound and outbound communication </para></listitem><listitem><para> Record processors plugged into deployed endpoints; handlers collect records and send them to every processors through the current endpoint. Processors may store records, convert them, log them, ... </para></listitem><listitem><para> MBean views of processors that can be used to configure and fine tune recording at runtime </para></listitem><listitem><para> Record filters allowing selection of information to be recorded as well as providing means of performing custom queries on the saved records.</para></listitem></itemizedlist><para> </para><section id="JBossWS-Recordsmanagement_Server_side"><title>Server side</title><para>On server side records are collected by JAX-WS handlers and pa!
ssed to the configured processors. JBossWS comes with two default record processors that are plugged into every endpoint during the deployment:</para><itemizedlist><listitem><para> LogRecorder: a simple record processor that writes records to the configured log. </para></listitem><listitem><para> MemoryBufferRecorder: a record processor that keeps the last received records in memory and allows user to search / get statistics on them. </para></listitem></itemizedlist><para>Every processors can be fine tuned to process some record attributes only according to the user and/or performance requirements. Default processors are not in recording mode upon creation, thus you need to switch them to recording mode through their MBean interfaces (see the <emphasis>Recording</emphasis> flag in the jmx-console).</para><para>Common processor properties and their respective defaults values are:</para><itemizedlist><listitem><para> processDestinationHost (true) </para></listitem><listitem><!
para> processSourceHost (true) </para></listitem><listitem><pa!
ra> proc
essHeaders (true) </para></listitem><listitem><para> processEnvelope (true) </para></listitem><listitem><para> processMessageType (true) </para></listitem><listitem><para> processOperation (true) </para></listitem><listitem><para> processDate (true) </para></listitem><listitem><para> recording (false) </para></listitem></itemizedlist><para>The recorders can be configured in the stacks bean configuration</para><screen xml:space="preserve"> <!-- Installed Record Processors-->
+ <bean name="WSMemoryBufferRecorder" class="org.jboss.wsf.framework.management.recording.MemoryBufferRecorder">
+ <property name="recording">false</property>
+ </bean>
+ <bean name="WSLogRecorder" class="org.jboss.wsf.framework.management.recording.LogRecorder">
+ <property name="recording">false</property>
+ </bean>
+</screen><para>The recording system is available for all the JBossWS supported stacks. However slightly different procedure is required to enable it depending on the used stack.</para><variablelist><varlistentry><term><emphasis role="bold">Native stack</emphasis> </term><listitem/></varlistentry></variablelist><para>Native stack comes with <ulink url="http://community.jboss.org/docs/DOC-13512">JBossWS - JAX-WS Endpoint Configuration</ulink>. The default standard endpoint already has the server side recording handler:</para><screen xml:space="preserve"> <endpoint-config>
+ <config-name>Standard Endpoint</config-name>
+ <pre-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>Recording Handler</javaee:handler-name>
+ <javaee:handler-class>org.jboss.wsf.framework.invocation.RecordingServerHandler</javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+ </pre-handler-chains>
+ </endpoint-config>
+</screen><para>thus nothing is required to use it since it is automatically installed in the pre-handler-chain. Of course you might want to add it to other endpoint configurations you're using.</para><variablelist><varlistentry><term><emphasis role="bold">Metro and CXF stacks </emphasis></term><listitem/></varlistentry></variablelist><para>Other stacks require users to manually add the <emphasis>org.jboss.wsf.framework.invocation.RecordingServerHandler</emphasis> to their endpoint handler chain. This can be done <link linkend="chap_JBossWS-UserGuide">the same way common user handlers are added</link>.</para><para>Once the handler is properly added to the chain, log recording configuration is agnostic to the used stack. Users just need to tune the processors parameters though their MBean interfaces.</para><para> </para></section>
+<section id="JBossWS-Recordsmanagement_Client_side"><title>Client side</title><para>JMX management of processors is of course available on server side only. However users might also be interested in collecting and processing records on client side. Since handlers can be set on client side too, customer handlers could be configured to capture messages almost like the <emphasis>RecordingServerHandler</emphasis> does. This is left to the users since it is directly linked to their custom needs. For instance a common use could be to pass client side collected records to the LogRecorder.</para><para> </para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_Advanced_hints"><title>Advanced hints</title><section id="JBossWS-Recordsmanagement_Adding_custom_recorders"><title>Adding custom recorders</title><para>As previously said, the recording system is extensible: JBossWS users can write their own processors and plug them at runtime into their deployed endpoints through the <emphasis>addRecordProcessor</emphasis> functionality of the ManagedEndpoint MBean. Every processor needs to implement the <emphasis>org.jboss.wsf.spi.management.recording.RecordProcessor</emphasis> interface. Then you can choose one of the two following options:</para><itemizedlist><listitem><para> Give you record processor an MBean interface declaring the manageable attributes: the recording system will plug your processor to the endpoint and register a management MBean for it using your interface. This allows you to create highly configurable custom processors. For an example of this development option, take a look at!
the <emphasis>org.jboss.wsf.framework.management.recording.MemoryBufferRecorder</emphasis>. </para></listitem><listitem><para> Add your record processor to the managed endpoint as is: the recording system will plug it to the endpoint and register a standard management MBean for its basic processing configuration. The <emphasis>org.jboss.wsf.framework.management.recording.LogRecorder</emphasis> is an example of this development option. </para></listitem></itemizedlist><para>A code snippet showing how to get the MBeanProxy instance which you can invoke MBean with can be found <link linkend="chap_JBossWS-Endpointmanagement">here</link>.</para></section>
+<section id="JBossWS-Recordsmanagement_Handlers_position"><title>Handler's position</title><para>Of course the recording handler's position in the handler chain influences the collected records. As a matter of fact some information may or may not be available at a given point of the handler chain execution. The standard endpoint configuration declares the RecordingServerHandler into the pre-handler-chain. Speaking of the native stack, this means for example that you'll get the invoked operation data and that decrypted messages will be recorded if using WS-Security, since the WS-Security handler runs in the post-handler-chain. Users might want to change the recording handler's position in the chain according to their requirements.</para></section>
+<section id="JBossWS-Recordsmanagement_Multiple_handlers"><title>Multiple handlers</title><para>Records attributes include a record group ID that is meant to link records whose messages belong to the same message flow (a request-response for example). In order to set the right group ID to the records, the current ID is associated to the thread that is processing the endpoint invocation. This means that multiple related records can be linked together and extracted together from a processor.</para><para>For this reason, you might want to install multiple recording handlers into different points of the handler chain. For instance, it could make sense to record messages both before and after encryption/decryption when using WS-Security.</para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_Future_extensions"><title>Future extensions</title><para>This paragraph covers eventual future extensions and/or idea JBossWS users may want to leverage for their own business.</para><section id="JBossWS-Recordsmanagement_Database_recorder"><title>Database recorder</title><para>The MemoryBufferRecorder provides interesting functionalities to query the collected records set. For obvious reasons, records are discarded once a given size of the buffer is reached.</para><para>A DB based recorder could be developed; it should work the same way the MemoryBufferRecorder does, except for records that should be saved through a given datasource. This will provide persistence of data even in case of application server reboot and webservice application redeploy. It will also allow records coming from different node of a cluster to be stored together. Finally this would allow administrators to directly query the database, which might be far more eff!
icient.</para></section>
+<section id="JBossWS-Recordsmanagement_Custom_log_writer"><title>Custom log writer</title><para>The idea of getting statistics from collected records could be further exploited getting custom logs from the records. These logs could be outputted by a custom processor in standard or proprietary formats allowing them to be imported into eventual third-party log processing tools which might offer complex/funky graphic or statistic functionalities and so on.</para></section>
+</section>
+<section id="JBossWS-Recordsmanagement_References"><title>References</title><para>You might want to take a look at the <emphasis>org.jboss.wsf.framework.management.recording</emphasis> and <emphasis>org.jboss.wsf.spi.management.recording</emphasis> packages in the source code to better understand how all this works and can be used.</para></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-Securetransport.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-Securetransport.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-Securetransport.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-Securetransport"><title>JBossWS-Securetransport</title><para/><para>JBossWS allows you to require that requests to a given endpoint use SSL by specifying the <emphasis>transportGuarantee</emphasis> attribute in the <ulink url="http://community.jboss.org/docs/DOC-13972#WebContext">@WebContext</ulink> annotation.</para><para>Here is an example using a SLSB endpoint:</para><screen xml:space="preserve">@Stateless
+@SecurityDomain("JBossWS")
+@RolesAllowed("friend")
+@WebContext
+(
+ contextRoot="/my-cxt",
+ urlPattern="/*",
+ authMethod="BASIC",
+ transportGuarantee="CONFIDENTIAL",
+ secureWSDLAccess=<emphasis role="bold">false</emphasis>
+)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointEJB <emphasis role="bold">implements</emphasis> EndpointInterface
+{
+ ...
+}
+</screen><para>Similarly to enforce the same requirement on POJO endpoints, you need to edit web.xml and add a user-data-constraint element to your security-constraint element:</para><screen xml:space="preserve"> <security-constraint>
+ <web-resource-collection>
+ <web-resource-name>All resources</web-resource-name>
+ <url-pattern>/*</url-pattern>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>friend</role-name>
+ </auth-constraint>
+ <user-data-constraint>
+ <transport-guarantee>CONFIDENTIAL</transport-guarantee>
+ </user-data-constraint>
+ </security-constraint>
+
+ <security-role>
+ <role-name>friend</role-name>
+ </security-role>
+</screen><para>If you're manually creating your service contract, make sure that the endpoint address in your WSDL file uses a secure protocol. The easiest way is to add "<ulink url="https://">https://</ulink>" to the SOAP Address entry:</para><screen xml:space="preserve"> <service name="MyService">
+ <port name="BasicSecuredPort" binding="tns:MyBinding">
+ <soap:address location="<ulink url="https://localhost:8443/my-ctx/SecureEndpoint">https://localhost:8443/my-ctx/SecureEndpoint</ulink>"/>
+ </port>
+ </service>
+</screen><para>For this to work the Tomcat+SSL connector must be enabled:</para><screen xml:space="preserve"> <Connector port="8443" address="${jboss.bind.address}"
+ maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+ scheme="https" secure="true" clientAuth="want"
+ keystoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ keystorePass="jbossws"
+ truststoreFile="${jboss.server.home.dir}/conf/keystores/wsse.keystore"
+ truststorePass="jbossws"
+ sslProtocol = "TLS" />
+</screen><para>Please refer the <ulink url="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">Tomcat-5.5 SSL Configuration HOWTO</ulink> for further details.</para><para> </para><section id="JBossWS-Securetransport_Client_side"><title>Client side</title><para>On the client side the truststore must be installed:</para><screen xml:space="preserve"> <sysproperty key="javax.net.ssl.keyStore" value="${test.resources.dir}/wsse/wsse.keystore"/>
+ <sysproperty key="javax.net.ssl.trustStore" value="${test.resources.dir}/wsse/wsse.truststore"/>
+ <sysproperty key="javax.net.ssl.keyStorePassword" value="jbossws"/>
+ <sysproperty key="javax.net.ssl.trustStorePassword" value="jbossws"/>
+ <sysproperty key="javax.net.ssl.keyStoreType" value="jks"/>
+ <sysproperty key="javax.net.ssl.trustStoreType" value="jks"/></screen><para>As you can see, this requires you to setup the environment specifying both the location and type of your truststore.</para><para>Finally, in case you see the following exception:</para><screen xml:space="preserve"> java.io.IOException: HTTPS hostname wrong: should be <localhost>
+ at sun.net.www.protocol.https.HttpsClient.checkURLSpoofing(HttpsClient.java:493)
+ at sun.net.www.protocol.https.HttpsClient.afterConnect(HttpsClient.java:418)
+</screen><para>you should disable URL checking on the client side:</para><screen xml:space="preserve"> <sysproperty key="org.jboss.security.ignoreHttpsHost" value="true"/></screen></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-StackCXFUserGuide.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-StackCXFUserGuide.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-StackCXFUserGuide.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,382 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-StackCXFUserGuide"><title>JBossWS-StackCXFUserGuide</title><note><para><para>This page covers features available in <emphasis role="bold">JBossWS CXF stack only</emphasis>. <link linkend="chap_JBossWS-UserGuide">Please refer to the common user guide</link> for a basic introduction to JAX-WS programming as well as documentation on all features, tools, etc. the JBossWS Web Service Framework provides for every supported stack (including CXF stack).</para><para> </para> <para>Also please note this page does not go through the documentation of every feature, option, etc. provided by Apache CXF; on the countrary the only topics covered here are specific issues regarding integration with JBoss and stack specific features provided by JBossWS Web Service Framework for the CXF stack. A few tutorials are also provided for show how to leverage some WS technologies.</para> <para>The <emphasis>official Apache CXF documentat!
ion</emphasis> is available <ulink url="http://cxf.apache.org">here</ulink>.</para></para></note><para/><para> </para><section id="JBossWS-StackCXFUserGuide_JBossWS_CXF_Integration"><title>JBossWS CXF Integration</title><section id="JBossWS-StackCXFUserGuide_Creating_a_Bus_instance"><title>Creating a Bus instance</title><para>Most of the Apache CXF features are configurable using the <emphasis>org.apache.cxf.Bus</emphasis> class. New Bus instances are produced by the currently configured <emphasis>org.apache.cxf.BusFactory</emphasis> implementation the following way:</para><screen xml:space="preserve">Bus bus = BusFactory.newInstance().createBus();
+</screen><para>The algorithm for selecting the actual implementation of BusFactory to be used leverages the Service API, basically looking for optional configurations in META-INF/services/... location using the current classloader. JBossWS-CXF integration comes with his own implementation of BusFactory, <emphasis>org.jboss.wsf.stack.cxf.client.configuration.JBossWSBusFactory</emphasis>, that allows for automatic detection of Spring availability as well as seamless setup of JBossWS customizations on top of Apache CXF. JBossWSBusFactory is <emphasis>automatically</emphasis> retrieved by the BusFactory.newInstance() call above.</para><para> </para><para>JBossWS users willing to explicitely use functionalities of <emphasis>org.apache.cxf.bus.spring.SpringBusFactory</emphasis> or <emphasis>org.apache.cxf.bus.CXFBusFactory,</emphasis> get the same API with JBossWS additions through JBossWSBusFactory:</para><screen xml:space="preserve">String myConfigFile = ...
+Bus bus = <emphasis role="bold">new</emphasis> JBossWSBusFactory().createBus(myConfigFile);
+</screen><para> </para><screen xml:space="preserve">Map<Class, Object> myExtensions = <emphasis role="bold">new</emphasis> HashMap<Class, Object>();
+myExtensions.put(...);
+Bus bus = <emphasis role="bold">new</emphasis> JBossWSBusFactory().createBus(myExtensions);
+</screen></section>
+<section id="JBossWS-StackCXFUserGuide_Server_Side_Integration_Customization"><title>Server Side Integration Customization</title><para>It is possible to customize the JBossWS and CXF integration by incorporating the CXF configuration file to the endpoint deployment archive. In order for that to be possible, JBossWS-CXF requires Spring to be installed in the application server. The Spring Framework libraries installation can be perfomed using the <ulink url="http://community.jboss.org/docs/DOC-13545">JBossWS-CXF installation</ulink>.</para><para>The convention is the following:</para><itemizedlist><listitem><para> file name must be <emphasis role="bold">jbossws-cxf.xml</emphasis> </para></listitem><listitem><para> for POJO deployments it is located in <emphasis role="bold">WEB-INF</emphasis> directory </para></listitem><listitem><para> for EJB3 deployments it is located in <emphasis role="bold">META-INF</emphasis> directory </para></listitem></itemizedlist><para>If user do !
not provide its own CXF configuration file, a default one is automatically generated during the deployment.</para><para>For POJO deployments the generated <emphasis role="bold">jbossws-cxf.xml</emphasis> has the following content:</para><screen xml:space="preserve"><beans
+ xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xsi:schemaLocation='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans.xsd">http://www.springframework.org/schema/beans/spring-beans.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>
+ <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>'>
+
+ <!-- one or more jaxws:endpoint POJO declarations -->
+ <jaxws:endpoint
+ id='POJOEndpoint'
+ address='<ulink url="http://localhost:8080/pojo_endpoint_archive_name">http://localhost:8080/pojo_endpoint_archive_name</ulink>'
+ implementor='my.package.POJOEndpointImpl'>
+ <jaxws:invoker>
+ <bean class='org.jboss.wsf.stack.cxf.InvokerJSE'/>
+ </jaxws:invoker>
+ </jaxws:endpoint></beans>
+</screen><para>For EJB3 deployments the generated <emphasis role="bold">jbossws-cxf.xml</emphasis> has the following content:</para><screen xml:space="preserve"><beans
+ xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xsi:schemaLocation='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans.xsd">http://www.springframework.org/schema/beans/spring-beans.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>
+ <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>'>
+
+ <!-- one or more jaxws:endpoint EJB3 declarations -->
+ <jaxws:endpoint
+ id='EJB3Endpoint'
+ address='<ulink url="http://localhost:8080/ejb3_endpoint_archive_name">http://localhost:8080/ejb3_endpoint_archive_name</ulink>'
+ implementor='my.package.EJB3EndpointImpl'>
+ <jaxws:invoker>
+ <bean class='org.jboss.wsf.stack.cxf.InvokerEJB3'/>
+ </jaxws:invoker>
+ </jaxws:endpoint></beans>
+</screen><para>Providing custom CXF configuration to the endpoint deployment is useful in cases when users want to use features that are not part of standard JAX-WS specification but CXF implements them. For example see <link linkend="chap_JBossWS-CXFWS-ReliableMessagingtutorial">CXF WS-RM tutorial</link> customization file. We are providing custom CXF endpoint configuration there to turn on WS-RM feature for endpoint.</para><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>When user incorporates its own CXF configuration to the endpoint archive he must reference either <emphasis role="bold">org.jboss.wsf.stack.cxf.InvokerJSE</emphasis> or <emphasis role="bold">org.jboss.wsf.stack.cxf.InvokerEJB3</emphasis> jaxws invoker bean there for each jaxws endpoint.</emphasis></para><para> </para></para></note></section>
+</section>
+<section id="JBossWS-StackCXFUserGuide_Extended_Features"><title>Extended Features</title><para><ulink url="http://cwiki.apache.org/CXF20DOC/ws-support.html">Here</ulink> is the CXF documentation about supported WS-* specifications.</para><para> </para><section id="JBossWS-StackCXFUserGuide_WSAddressing"><title>WS-Addressing</title><para>Apache CXF has a thorough support for WS-Addressing; details are available at the following pages:</para><para><ulink url="http://cwiki.apache.org/CXF20DOC/ws-addressing.html">CXF WS-Addressing documentation</ulink> <ulink url="http://cwiki.apache.org/CXF20DOC/wsaconfiguration.html">CXF WS-Addressing configuration</ulink></para><para> </para><para>Given the JAXWS specification currently covers WS-Addressing basic fuctionalities, users simply needing to enable it can make use of the @Addressing annotation and AddressingFeature, as shown in the following JBossWS-CXF tutorial:</para><para><link linkend="chap_JBossWS-CXFWS-Addressingtutorial"!
>JBossWS-CXF WS-Addressing Tutorial</link></para><para> </para></section>
+<section id="JBossWS-StackCXFUserGuide_WSReliableMessaging"><title>WS-ReliableMessaging</title><para>The Apache CXF technical documentation on WS-RealiableMessaging is available as a reference at the following pages:</para><para><ulink url="http://cwiki.apache.org/CXF20DOC/ws-reliablemessaging.html">CXF WS-ReliableMessaging documentation</ulink> <ulink url="http://cwiki.apache.org/CXF20DOC/wsrmconfiguration.html">CXF WS-ReliableMessaging configuration</ulink></para><para> </para><para>For a complete tutorial on how to enable WS-ReliableMessaging in a user client-server application, please take a look at:</para><para><link linkend="chap_JBossWS-CXFWS-ReliableMessagingtutorial">JBossWS-CXF WS-ReliableMessaging Tutorial</link></para><para> </para></section>
+<section id="JBossWS-StackCXFUserGuide_WSPolicy"><title>WS-Policy</title><para>Apache CXF technical documentation on the WS-Policy engine and its configuration is available at:</para><para><ulink url="http://cwiki.apache.org/CXF20DOC/ws-policy.html">CXF WS-Policy documentation</ulink> <ulink url="http://cwiki.apache.org/CXF20DOC/wspconfiguration.html">CXF WS-Policy configuration</ulink></para><para> </para><para>For a complete sample of WS-Policy usage, please take a look at the JBossWS-CXF WS-ReliableMessaging tutorial below, as WS-RM is implemented leveraging policies there:</para><para><link linkend="chap_JBossWS-CXFWS-ReliableMessagingtutorial">JBossWS-CXF WS-Policy & WS-ReliableMessaging Tutorial</link></para><para> </para><section id="JBossWS-StackCXFUserGuide_Note_on_PolicyEngine_setup"><title>Note on PolicyEngine setup</title><para>When building up the Bus without Spring libraries available on the classpath, JBossWSBusFactory still makes sure the PolicyEngine !
(as well as the RMManager) is properly setup. This allows users to leverage basic WS-Policy functionalities the same way they'd do with a full Spring-enabled Bus.</para><para> </para></section>
+</section>
+<section id="JBossWS-StackCXFUserGuide_WSSecurity"><title>WS-Security</title><para><ulink url="http://cxf.apache.org/">Apache CXF</ulink> leverages <ulink url="http://ws.apache.org/wss4j/">WSS4J</ulink> to provide WS-Security functionalities. This means that thanks to the JBossWS-CXF integration, users can create web service applications using CXF - WSS4J implementation of WS-Security and deploy them on JBoss Application Server.</para><para> </para><section id="JBossWS-StackCXFUserGuide_WSS4J_security_on_JBoss"><title>WSS4J security on JBoss</title><para>The Apache CXF documentation features an brief chapter on <ulink url="http://cwiki.apache.org/CXF20DOC/ws-security.html">how to use WSS4J security in CXF</ulink>. Here below instead you'll find some explanations on how to create a simple application and what you need to do to leverage WSS4J security on JBoss.</para><para> </para><variablelist><varlistentry><term><emphasis role="bold">Creating the web service endpoint </em!
phasis></term><listitem/></varlistentry></variablelist><para>First of all you need to create the web service endpoint / client using JAX-WS. This can be achieved in many ways, for instance you might want to:</para><orderedlist><listitem><para> write your endpoint implementation, then run the <emphasis role="bold"><emphasis>wsprovide</emphasis></emphasis> JBoss commandline tool which generates the service contract (bottom-up approach); </para></listitem><listitem><para> run the <emphasis role="bold"><emphasis>wsconsume</emphasis></emphasis> JBoss commandline tool to get the client artifacts from the service contract (top-down approach); </para></listitem><listitem><para> write your client implementation. </para></listitem></orderedlist><para> </para><variablelist><varlistentry><term><emphasis role="bold">Turn on WS-Security </emphasis></term><listitem/></varlistentry></variablelist><para>WSS4J security is triggered through interceptors that are added to the service and/or c!
lient. These interceptors allows you to perform the most commo!
n WS-Sec
urity related process:</para><itemizedlist><listitem><para> pass authentication tokens between services; </para></listitem><listitem><para> encrypt messages or parts of messages; </para></listitem><listitem><para> sign messages; </para></listitem><listitem><para> timestamp messages. </para></listitem></itemizedlist><para>Interceptors can be added either programmatically or through the Spring xml configuration of endpoints.</para><para>For instance, on server side, you can configure signature and encryption in the <emphasis>jboss-cxf.xml</emphasis> file this way:</para><screen xml:space="preserve"><beans
+ xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xsi:schemaLocation='<ulink url="http://cxf.apache.org/core">http://cxf.apache.org/core</ulink>
+ <ulink url="http://cxf.apache.org/schemas/core.xsd">http://cxf.apache.org/schemas/core.xsd</ulink>
+ <ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>
+ <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>'>
+
+ <bean id="Sign_Request" class="org.apache.cxf.ws.security.wss4j.WSS4JInInterceptor">
+ <constructor-arg>
+ <map>
+ <entry key="action" value="Timestamp Signature Encrypt"/>
+ <entry key="signaturePropFile" value="bob.properties"/>
+ <entry key="decryptionPropFile" value="bob.properties"/>
+ <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback"/>
+ </map>
+ </constructor-arg>
+ </bean>
+
+ <bean id="Sign_Response" class="org.apache.cxf.ws.security.wss4j.WSS4JOutInterceptor">
+ <constructor-arg>
+ <map>
+ <entry key="action" value="Timestamp Signature Encrypt"/>
+ <entry key="user" value="bob"/>
+ <entry key="signaturePropFile" value="bob.properties"/>
+ <entry key="encryptionPropFile" value="bob.properties"/>
+ <entry key="encryptionUser" value="Alice"/>
+ <entry key="signatureKeyIdentifier" value="DirectReference"/>
+ <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback"/>
+ <entry key="signatureParts" value="{Element}{<ulink url="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...">http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utilit...</ulink>}Timestamp;{Element}{<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>}Body"/>
+ <entry key="encryptionParts" value="{Element}{<ulink url="http://www.w3.org/2000/09/xmldsig#">http://www.w3.org/2000/09/xmldsig#</ulink>}Signature;{Content}{<ulink url="http://schemas.xmlsoap.org/soap/envelope/">http://schemas.xmlsoap.org/soap/envelope/</ulink>}Body"/>
+ <entry key="encryptionKeyTransportAlgorithm" value="<ulink url="http://www.w3.org/2001/04/xmlenc#rsa-1_5">http://www.w3.org/2001/04/xmlenc#rsa-1_5</ulink>"/>
+ <entry key="encryptionSymAlgorithm" value="<ulink url="http://www.w3.org/2001/04/xmlenc#tripledes-cbc">http://www.w3.org/2001/04/xmlenc#tripledes-cbc</ulink>"/>
+ </map>
+ </constructor-arg>
+ </bean>
+
+ <jaxws:endpoint
+ id='ServiceImpl'
+ address='<ulink url="http://@jboss.bind.address@:8080/jaxws-samples-wsse-sign-encrypt">http://@jboss.bind.address@:8080/jaxws-samples-wsse-sign-encrypt</ulink>'
+ implementor='org.jboss.test.ws.jaxws.samples.wsse.ServiceImpl'>
+ <jaxws:invoker>
+ <bean class='org.jboss.wsf.stack.cxf.InvokerJSE'/>
+ </jaxws:invoker>
+ <jaxws:outInterceptors>
+ <bean class="org.apache.cxf.binding.soap.saaj.SAAJOutInterceptor"/>
+ <ref bean="Sign_Response"/>
+ </jaxws:outInterceptors>
+ <jaxws:inInterceptors>
+ <ref bean="Sign_Request"/>
+ <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
+ </jaxws:inInterceptors>
+ </jaxws:endpoint>
+</beans>
+</screen><para>This specifies the whole security configuration (including algorithms and elements to be signed/encrypted); moreover it references a properties file (<emphasis>bob.properties</emphasis>) providing the keystore-related information:</para><screen xml:space="preserve">org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
+org.apache.ws.security.crypto.merlin.keystore.type=jks
+org.apache.ws.security.crypto.merlin.keystore.password=password
+org.apache.ws.security.crypto.merlin.keystore.alias=bob
+org.apache.ws.security.crypto.merlin.file=bob.jks
+</screen><para>As you can see in the <emphasis>jbossws-cxf.xml</emphasis> file above, a keystore password callback handler is also configured; while the properties file has the password for the keystore, this callback handler is used to set password for each key (it has to match the one used when each key was imported in the store). Here's a trivial example:</para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsse;
+
+<emphasis role="bold">import</emphasis> java.io.IOException;
+<emphasis role="bold">import</emphasis> java.util.HashMap;
+<emphasis role="bold">import</emphasis> java.util.Map;
+
+<emphasis role="bold">import</emphasis> javax.security.auth.callback.Callback;
+<emphasis role="bold">import</emphasis> javax.security.auth.callback.CallbackHandler;
+<emphasis role="bold">import</emphasis> javax.security.auth.callback.UnsupportedCallbackException;
+<emphasis role="bold">import</emphasis> org.apache.ws.security.WSPasswordCallback;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> KeystorePasswordCallback <emphasis role="bold">implements</emphasis> CallbackHandler
+{
+ <emphasis role="bold">private</emphasis> Map<String, String> passwords = <emphasis role="bold">new</emphasis> HashMap<String, String>();
+
+ <emphasis role="bold">public</emphasis> KeystorePasswordCallback()
+ {
+ passwords.put("alice", "password");
+ passwords.put("bob", "password");
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> handle(Callback[] callbacks) <emphasis role="bold">throws</emphasis> IOException, UnsupportedCallbackException
+ {
+ <emphasis role="bold">for</emphasis> (<emphasis role="bold">int</emphasis> i = 0; i < callbacks.length; i++)
+ {
+ WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];
+ String pass = passwords.get(pc.getIdentifer());
+ <emphasis role="bold">if</emphasis> (pass != <emphasis role="bold">null</emphasis>)
+ {
+ pc.setPassword(pass);
+ <emphasis role="bold">return</emphasis>;
+ }
+ }
+ }
+
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> setAliasPassword(String alias, String password)
+ {
+ passwords.put(alias, password);
+ }
+}
+</screen><para>On client side, you can similarly setup the interceptors programmatically; here is an excerpt of the client for the above described endpoint (of course you can also leverage a proper Spring configuration for loading an already configured CXF Bus instance):</para><screen xml:space="preserve">Endpoint cxfEndpoint = client.getEndpoint();
+Map<String,Object> outProps = <emphasis role="bold">new</emphasis> HashMap<String,Object>();
+outProps.put("action", "Timestamp Signature Encrypt");
+outProps.put("user", "alice");
+outProps.put("signaturePropFile", "META-INF/alice.properties");
+outProps.put("signatureKeyIdentifier", "DirectReference");
+outProps.put("passwordCallbackClass", "org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback");
+outProps.put("signatureParts", "{Element}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body");
+outProps.put("encryptionPropFile", "META-INF/alice.properties");
+outProps.put("encryptionUser", "Bob");
+outProps.put("encryptionParts", "{Element}{http://www.w3.org/2000/09/xmldsig#}Signature;{Content}{http://schemas.xmlsoap.org/soap/envelope/}Body");
+outProps.put("encryptionSymAlgorithm", "http://www.w3.org/2001/04/xmlenc#tripledes-cbc");
+outProps.put("encryptionKeyTransportAlgorithm", "http://www.w3.org/2001/04/xmlenc#rsa-1_5");
+WSS4JOutInterceptor wssOut = <emphasis role="bold">new</emphasis> WSS4JOutInterceptor(outProps); //request
+cxfEndpoint.getOutInterceptors().add(wssOut);
+cxfEndpoint.getOutInterceptors().add(<emphasis role="bold">new</emphasis> SAAJOutInterceptor());
+
+Map<String,Object> inProps= <emphasis role="bold">new</emphasis> HashMap<String,Object>();
+inProps.put("action", "Timestamp Signature Encrypt");
+inProps.put("signaturePropFile", "META-INF/alice.properties");
+inProps.put("passwordCallbackClass", "org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback");
+inProps.put("decryptionPropFile", "META-INF/alice.properties");
+WSS4JInInterceptor wssIn = <emphasis role="bold">new</emphasis> WSS4JInInterceptor(inProps); //response
+cxfEndpoint.getInInterceptors().add(wssIn);
+cxfEndpoint.getInInterceptors().add(<emphasis role="bold">new</emphasis> SAAJInInterceptor());
+</screen><variablelist><varlistentry><term/><listitem/></varlistentry><varlistentry><term><emphasis role="bold">Package and deploy </emphasis></term><listitem/></varlistentry></variablelist><para>To deploy your web service endpoint, you need to package the following files along with your service implementation and wsdl contract:</para><itemizedlist><listitem><para> the jbossws-cxf.xml descriptor </para></listitem><listitem><para> the properties file </para></listitem><listitem><para> the keystore file (if required for signature/encryption) </para></listitem><listitem><para> the keystore password callback handler class </para></listitem></itemizedlist><para>For instance, here are the archive contents for the afore mentioned signature & encryption sample (POJO endpoint):</para><screen xml:space="preserve">[alessio@localhost cxf-tests]$ jar -tvf target/test-libs/jaxws-samples-wsse-sign-encrypt.war
+ 0 Tue Jun 03 19:41:26 CEST 2008 META-INF/
+ 106 Tue Jun 03 19:41:24 CEST 2008 META-INF/MANIFEST.MF
+ 0 Tue Jun 03 19:41:26 CEST 2008 WEB-INF/
+ 0 Tue Jun 03 19:41:26 CEST 2008 WEB-INF/classes/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/
+1628 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/KeystorePasswordCallback.class
+ 364 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/ServiceIface.class
+ 859 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/ServiceImpl.class
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/
+ 685 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/SayHello.class
+1049 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/SayHelloResponse.class
+2847 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/jbossws-cxf.xml
+ 0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/
+1575 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/SecurityService.wsdl
+ 641 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/SecurityService_schema1.xsd
+1820 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/bob.jks
+ 311 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/bob.properties
+ 573 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/web.xml
+</screen><para>On client side, instead, you only need the properties and keystore files (assuming you setup the interceptors programmatically).</para><para>Check that JBossWS-CXF is installed on your current JBoss Application Server, deploy and test your WS-Security-enabled application.</para><para> </para></section>
+<section id="JBossWS-StackCXFUserGuide_WSSecurity_Policies"><title>WS-Security Policies</title><para> </para><para>Starting from JBossWS-CXF 3.1.1, WS-Security Policy implementation is available and can be used to configure WS-Security more easily.</para><para>Please refer to the <ulink url="http://cwiki.apache.org/CXF20DOC/ws-securitypolicy.html">Apache CXF documentation</ulink>; basically instead of manually configuring interceptors in the client or through jbossws-cxf.xml descriptor, you simply provide the right policies in the WSDL contract.</para><screen xml:space="preserve"> ...
+ <binding name="SecurityServicePortBinding" type="tns:ServiceIface">
+ <wsp:PolicyReference URI="#SecurityServiceSignPolicy"/>
+ ...
+ <wsp:Policy wsu:Id="SecurityServiceSignPolicy"
+ xmlns:sp="<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy</ulink>">
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:AsymmetricBinding xmlns:sp='<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy</ulink>'>
+ <wsp:Policy>
+ <sp:InitiatorToken>
+ <wsp:Policy>
+ <sp:X509Token sp:IncludeToken='<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysT...">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysT...</ulink>'>
+ <wsp:Policy>
+ <sp:WssX509V3Token10 />
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:InitiatorToken>
+ <sp:RecipientToken>
+ <wsp:Policy>
+ <sp:X509Token sp:IncludeToken='<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Always</ulink>'>
+ <wsp:Policy>
+ <sp:WssX509V3Token10 />
+ </wsp:Policy>
+ </sp:X509Token>
+ </wsp:Policy>
+ </sp:RecipientToken>
+ <sp:AlgorithmSuite>
+ <wsp:Policy>
+ <sp:Basic256 />
+ </wsp:Policy>
+ </sp:AlgorithmSuite>
+ <sp:Layout>
+ <wsp:Policy>
+ <sp:Strict />
+ </wsp:Policy>
+ </sp:Layout>
+ <sp:OnlySignEntireHeadersAndBody />
+ </wsp:Policy>
+ </sp:AsymmetricBinding>
+ <sp:Wss10 xmlns:sp='<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy</ulink>'>
+ <wsp:Policy>
+ <sp:MustSupportRefEmbeddedToken />
+ </wsp:Policy>
+ </sp:Wss10>
+ <sp:SignedParts xmlns:sp='<ulink url="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">http://schemas.xmlsoap.org/ws/2005/07/securitypolicy</ulink>'>
+ <sp:Body />
+ </sp:SignedParts>
+ </wsp:All>
+ </wsp:ExactlyOne>
+ </wsp:Policy>
+ ...
+</screen><para>Just few properties are also required to be set either in the message context or in the jbossws-cxf.xml descriptor.</para><screen xml:space="preserve">((BindingProvider)proxy).getRequestContext().put(SecurityConstants.CALLBACK_HANDLER, <emphasis role="bold">new</emphasis> KeystorePasswordCallback());
+((BindingProvider)proxy).getRequestContext().put(SecurityConstants.SIGNATURE_PROPERTIES, Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));
+((BindingProvider)proxy).getRequestContext().put(SecurityConstants.ENCRYPT_PROPERTIES, Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));
+</screen><screen xml:space="preserve"><beans
+ xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xsi:schemaLocation='<ulink url="http://cxf.apache.org/core">http://cxf.apache.org/core</ulink>
+ <ulink url="http://cxf.apache.org/schemas/core.xsd">http://cxf.apache.org/schemas/core.xsd</ulink>
+ <ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>
+ <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>'>
+
+ <jaxws:endpoint
+ id='ServiceImpl'
+ address='<ulink url="http://@jboss.bind.address@:8080/jaxws-samples-wssePolicy-sign">http://@jboss.bind.address@:8080/jaxws-samples-wssePolicy-sign</ulink>'
+ implementor='org.jboss.test.ws.jaxws.samples.wssePolicy.ServiceImpl'>
+
+ <jaxws:properties>
+ <entry key="ws-security.signature.properties" value="bob.properties"/>
+ <entry key="ws-security.encryption.properties" value="bob.properties"/>
+ <entry key="ws-security.callback-handler" value="org.jboss.test.ws.jaxws.samples.wssePolicy.KeystorePasswordCallback"/>
+ </jaxws:properties>
+ </jaxws:endpoint>
+</beans>
+</screen><para> </para></section>
+<section id="JBossWS-StackCXFUserGuide_Authentication_and_authorization"><title>Authentication and authorization</title><para> </para><para>The Username Token Profile can of course be used to provide client's credentials to the target endpoint. Starting from JBossWS-CXF 3.3.0 (which includes Apache CXF 2.2.8), the username token information can be used for authentication and authorization on JBoss AS (JAAS integration).</para><para>On server side, you need to specify what follows (for instance using a <emphasis>jbossws-cxf.xml</emphasis> descriptor):</para><itemizedlist><listitem><para>an interceptor for performing authentication and populating a valid SecurityContext; the provided interceptor should extend org.apache.cxf.ws.security.wss4j.AbstractUsernameTokenAuthenticatingInterceptor, in particular JBossWS integration comes with <emphasis>org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingInterceptor</emphasis> for this;</para></listitem><listitem><para>an in!
terceptor for performing authorization; CXF requires that to extend org.apache.cxf.interceptor.security.AbstractAuthorizingInInterceptor, for instance the <emphasis>SimpleAuthorizingInterceptor</emphasis> can be used for simply mapping endpoint operations to allowed roles.</para></listitem></itemizedlist><screen xml:space="preserve"><beans
+ xmlns='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:xsi='<ulink url="http://www.w3.org/2001/XMLSchema-instance">http://www.w3.org/2001/XMLSchema-instance</ulink>'
+ xmlns:beans='<ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>'
+ xmlns:jaxws='<ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>'
+ xmlns:util='<ulink url="http://www.springframework.org/schema/util">http://www.springframework.org/schema/util</ulink>'
+ xsi:schemaLocation='<ulink url="http://cxf.apache.org/core">http://cxf.apache.org/core</ulink>
+ <ulink url="http://cxf.apache.org/schemas/core.xsd">http://cxf.apache.org/schemas/core.xsd</ulink>
+ <ulink url="http://www.springframework.org/schema/util">http://www.springframework.org/schema/util</ulink>
+ <ulink url="http://www.springframework.org/schema/util/spring-util-2.0.xsd">http://www.springframework.org/schema/util/spring-util-2.0.xsd</ulink>
+ <ulink url="http://www.springframework.org/schema/beans">http://www.springframework.org/schema/beans</ulink>
+ <ulink url="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd</ulink>
+ <ulink url="http://cxf.apache.org/jaxws">http://cxf.apache.org/jaxws</ulink>
+ <ulink url="http://cxf.apache.org/schemas/jaxws.xsd">http://cxf.apache.org/schemas/jaxws.xsd</ulink>'>
+
+ <bean id="SecurityContextIn"
+ class="org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingInterceptor">
+ <constructor-arg>
+ <map>
+ <entry key="action" value="UsernameToken"/>
+ </map>
+ </constructor-arg>
+ </bean>
+
+ <util:map id="methodPermissions">
+ <entry key="sayHello" value="friend"/>
+ <entry key="greetMe" value="snoopies"/>
+ </util:map>
+
+ <bean id="AuthorizeIn"
+ class="org.apache.cxf.interceptor.security.SimpleAuthorizingInterceptor">
+ <property name="methodRolesMap" ref="methodPermissions"/>
+ </bean>
+
+ <jaxws:endpoint
+ id='ServiceImpl'
+ address='<ulink url="http://@jboss.bind.address@:8080/jaxws-samples-wsse-username-authorize">http://@jboss.bind.address@:8080/jaxws-samples-wsse-username-authorize</ulink>'
+ implementor='org.jboss.test.ws.jaxws.samples.wsse.ServiceImpl'>
+ <jaxws:inInterceptors>
+ <ref bean="SecurityContextIn"/>
+ <ref bean="AuthorizeIn"/>
+ <bean class="org.apache.cxf.binding.soap.saaj.SAAJInInterceptor"/>
+ </jaxws:inInterceptors>
+ </jaxws:endpoint>
+</beans></screen><para> </para><para>Authentication and authorization will simply be delegated to the security domain configured for the endpoint. Of course you can specify the login module you prefer for that security domain (refer the application server / security documentation for that).</para><para> </para><para>On client side, the username is provided through API (or a custom Spring configuration used to load the Bus):</para><para> </para><screen xml:space="preserve">Endpoint cxfEndpoint = client.getEndpoint();
+Map<String, Object> outProps = <emphasis role="bold">new</emphasis> HashMap<String, Object>();
+outProps.put("action", "UsernameToken");
+outProps.put("user", username);
+outProps.put("passwordType", "PasswordText");
+outProps.put("passwordCallbackClass", "org.jboss.test.ws.jaxws.samples.wsse.UsernamePasswordCallback");
+WSS4JOutInterceptor wssOut = <emphasis role="bold">new</emphasis> WSS4JOutInterceptor(outProps); //request
+cxfEndpoint.getOutInterceptors().add(wssOut);
+cxfEndpoint.getOutInterceptors().add(<emphasis role="bold">new</emphasis> SAAJOutInterceptor());
+</screen><para> </para><para>The password instead is provided through a password callback handler that needs to implement <emphasis>javax.security.auth.callback.CallbackHandler</emphasis>, similarly to the keystore's password callback handler.</para><para> </para><para>If you're running an older JBossWS-CXF version, or you're not interested in the the application server auth integration, you can use a password callback handler on server side too, configured through a WSS4JInInterceptor:</para><para> </para><screen xml:space="preserve"><bean id="UsernameToken_Request">
+ <constructor-arg>
+ <map>
+ <entry key="action" value="UsernameToken"/>
+ <entry key="passwordCallbackClass" value="org.jboss.test.ws.jaxws.samples.wsse.ServerUsernamePasswordCallback"/>
+ </map>
+ </constructor-arg>
+</bean>
+</screen><para> </para><screen xml:space="preserve"><emphasis role="bold">package</emphasis> org.jboss.test.ws.jaxws.samples.wsse;
+
+<emphasis role="bold">import</emphasis> java.io.IOException;
+<emphasis role="bold">import</emphasis> javax.security.auth.callback.CallbackHandler;
+<emphasis role="bold">import</emphasis> javax.security.auth.callback.UnsupportedCallbackException;
+<emphasis role="bold">import</emphasis> org.apache.ws.security.WSPasswordCallback;
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ServerUsernamePasswordCallback <emphasis role="bold">implements</emphasis> CallbackHandler
+{
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> handle(Callback[] callbacks) <emphasis role="bold">throws</emphasis> IOException, UnsupportedCallbackException
+ {
+ WSPasswordCallback pc = (WSPasswordCallback)callbacks[0];
+ <emphasis role="bold">if</emphasis> (!("kermit".equals(pc.getIdentifier()) && "thefrog".equals(pc.getPassword())))
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> SecurityException("User '" + pc.getIdentifier() + "' with password '" + pc.getPassword() + "' not allowed.");
+ }
+}
+</screen></section>
+<section id="JBossWS-StackCXFUserGuide_Further_information"><title>Further information</title><variablelist><varlistentry><term><emphasis role="bold">Samples </emphasis></term><listitem/></varlistentry></variablelist><para>The JBossWS-CXF source distribution comes with some samples using X.509 certificate signature and encryption as well as Username Token Profile. You can find them in package <emphasis>org.jboss.test.ws.jaxws.samples.wsse</emphasis> .</para><variablelist><varlistentry><term><emphasis role="bold">Crypto algorithms </emphasis></term><listitem/></varlistentry></variablelist><para>When requiring encryption, you might need to install an additional JCE provider supporting the crypto algorithms Apache CXF uses. This usually means the Bouncy Castle provider need to be configured in your JRE. Please refer the <ulink url="http://community.jboss.org/docs/DOC-13532">Native stack user</ulink> guide for further information about this.</para><para> </para></section>
+</section>
+<section id="JBossWS-StackCXFUserGuide_JMS_transport"><title>JMS transport</title><para><link linkend="chap_JBossWS-CXFJMStransporttutorial">Here</link> is a tutorial on how to deploy and invoke a JMS endpoint using JBossWS-CXF.</para><para> </para></section>
+</section>
+<section id="JBossWS-StackCXFUserGuide_HTTP_server_transport_setup"><title>HTTP server transport setup</title><para>Apache CXF comes with pluggable transport layers, allowing different transport modules to be used.</para><para> </para><para>The JBossWS-CXF integration leverages CXF servlet transport for the deployment of endpoints on top of the running JBoss Application Server.</para><para> </para><para>However, when users directly leverage the JAXWS <ulink url="http://download.oracle.com/javase/6/docs/api/javax/xml/ws/Endpoint.html#p...">Endpoint.publish(String s)</ulink> API, endpoints are expected to be deployed on a standalone http server started just for serving the specified endpoint. Apache CXF currently defaults to using the <ulink url="http://jetty.codehaus.org/jetty/">Jetty</ulink> based http transport. Starting <emphasis>from release 3.4.0</emphasis>, the JBossWS-CXF integration instead uses a different http transport module based on th!
e <ulink url="http://download.oracle.com/javase/6/docs/jre/api/net/httpserver/spec/com/...">http server</ulink> embedded in JDK6 distributions. Thanks to Apache CXF transport pluggability, users can still change the transport they want to use in this case by simply replacing the <emphasis>jbossws-cxf-transports-httpserver.jar</emphasis> library with another http transport one, for instance the <emphasis>cxf-rt-transports-http-jetty.jar</emphasis>.</para><para> </para></section>
+<section id="JBossWS-StackCXFUserGuide_SOAP_Message_Logging"><title>SOAP Message Logging</title><para>In the jbossws-cxf-client.jar[*] file you will find META-INF/cxf/cxf-extension-jbossws.xml, which contains the JBossWS extensions to the Apache CXF stack. In that file you need to enable</para><screen xml:space="preserve"> <cxf:bus>
+ <cxf:inInterceptors>
+ <ref bean="logInbound"/>
+ </cxf:inInterceptors>
+ <cxf:outInterceptors>
+ <ref bean="logOutbound"/>
+ </cxf:outInterceptors>
+ <cxf:inFaultInterceptors>
+ <ref bean="logOutbound"/>
+ </cxf:inFaultInterceptors>
+ </cxf:bus>
+</screen><para> </para><para>Once you've uncommented the cxf-extension-jbossws.xml contents, you need to re-pack the jar/zip.</para><para> </para><para>[*] The cxf-extension-jbossws.xml is available from version 3.2.2; if you don't have that file, you can manually add it and link it in cxf.extensions file.</para><para> </para><para>Finally, please note that logging can be enabled in many ways with Apache CXF, see the following documentation pages for instance:</para><itemizedlist><listitem><para><ulink url="http://cxf.apache.org/docs/configuration.html">http://cxf.apache.org/docs/configuration.html</ulink></para></listitem><listitem><para><ulink url="http://cxf.apache.org/docs/debugging-and-logging.html">http://cxf.apache.org/docs/debugging-and-logging.html</ulink></para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-UserGuide.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-UserGuide.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-UserGuide.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,475 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-UserGuide"><title>JBossWS-UserGuide</title><para/>
+<section id="JBossWS-UserGuide_Common_User_Guide"><title>Common User Guide</title><para> </para><para>Here below is the documentation that applies to every supported stacks. This includes basic JAX-WS usage as well as references to common additional functionalities the JBossWS Web Service Framework provides on top of the supported stacks.</para><section id="JBossWS-UserGuide_Web_Service_Concepts"><title>Web Service Concepts</title><section id="JBossWS-UserGuide_DocumentLiteral"><title>Document/Literal</title><para>With document style web services two business partners agree on the exchange of complex business documents that are well defined in XML schema. For example, one party sends a document describing a purchase order, the other responds (immediately or later) with a document that describes the status of the purchase order. No need to agree on such low level details as operation names and their associated parameters.</para><para>The payload of the SOAP message is an XM!
L document that can be validated against XML schema.</para><para>Document is defined by the style attribute on the SOAP binding.</para><screen xml:space="preserve"> <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
+ <soap:binding style='document' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='concat'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body use='literal'/>
+ </input>
+ <output>
+ <soap:body use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With document style web services the payload of every message is defined by a complex type in XML schema.</para><screen xml:space="preserve"> <complexType name='concatType'>
+ <sequence>
+ <element name='String_1' nillable='true' type='string'/>
+ <element name='long_1' type='long'/>
+ </sequence>
+ </complexType>
+ <element name='concat' type='tns:concatType'/>
+</screen><para>Therefore, message parts <emphasis role="bold">must</emphasis> refer to an <emphasis role="bold">element</emphasis> from the schema.</para><screen xml:space="preserve"> <message name='EndpointInterface_concat'>
+ <part name='parameters' element='tns:concat'/></message>
+</screen><para>The following message definition <emphasis role="bold">is invalid</emphasis>.</para><screen xml:space="preserve"> <message name='EndpointInterface_concat'>
+ <part name='parameters' type='tns:concatType'/></message></screen><section id="JBossWS-UserGuide_DocumentLiteral_Bare"><title>Document/Literal (Bare)</title><para>Bare is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a bare endpoint recognizable.</para><para>A bare endpoint or client uses a Java bean that represents the entire document payload.</para><screen xml:space="preserve">@WebService
+@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DocBareServiceImpl
+{
+ @WebMethod
+ <emphasis role="bold">public</emphasis> SubmitBareResponse submitPO(SubmitBareRequest poRequest)
+ {
+ ...
+ }
+}
+</screen><para>The trick is that the Java beans representing the payload contain JAXB annotations that define how the payload is represented on the wire.</para><screen xml:space="preserve">@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = "SubmitBareRequest", namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", propOrder = { "product" })
+@XmlRootElement(namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", name = "SubmitPO")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SubmitBareRequest
+{
+ @XmlElement(namespace="<ulink url="http://soapbinding.samples.jaxws.ws.test.jboss.org/">http://soapbinding.samples.jaxws.ws.test.jboss.org/</ulink>", required = <emphasis role="bold">true</emphasis>)
+ <emphasis role="bold">private</emphasis> String product;
+
+ ...
+}
+</screen></section>
+<section id="JBossWS-UserGuide_DocumentLiteral_Wrapped"><title>Document/Literal (Wrapped)</title><para>Wrapped is an implementation detail from the Java domain. Neither in the abstract contract (i.e. wsdl+schema) nor at the SOAP message level is a wrapped endpoint recognizable.</para><para>A wrapped endpoint or client uses the individual document payload properties. Wrapped is the default and does not have to be declared explicitly.</para><screen xml:space="preserve">@WebService
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> DocWrappedServiceImpl
+{
+ @WebMethod
+ @RequestWrapper (className="org.somepackage.SubmitPO")
+ @ResponseWrapper (className="org.somepackage.SubmitPOResponse")
+ <emphasis role="bold">public</emphasis> String submitPO(String product, <emphasis role="bold">int</emphasis> quantity)
+ {
+ ...
+ }
+}
+</screen><para>Note, that with JBossWS the request/response wrapper annotations are <emphasis role="bold">not required</emphasis>, they will be generated on demand using sensible defaults.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_RPCLiteral"><title>RPC/Literal</title><para>With RPC there is a wrapper element that names the endpoint operation. Child elements of the RPC parent are the individual parameters.</para><para>The SOAP body is constructed based on some simple rules:</para><itemizedlist><listitem><para> The port type operation name defines the endpoint method name </para></listitem><listitem><para> Message parts are endpoint method parameters </para></listitem></itemizedlist><para>RPC is defined by the style attribute on the SOAP binding.</para><screen xml:space="preserve"> <binding name='EndpointInterfaceBinding' type='tns:EndpointInterface'>
+ <soap:binding style='rpc' transport='<ulink url="http://schemas.xmlsoap.org/soap/http'/">http://schemas.xmlsoap.org/soap/http'/</ulink>>
+ <operation name='echo'>
+ <soap:operation soapAction=''/>
+ <input>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>' use='literal'/>
+ </input>
+ <output>
+ <soap:body namespace='<ulink url="http://org.jboss.ws/samples/jsr181pojo">http://org.jboss.ws/samples/jsr181pojo</ulink>' use='literal'/>
+ </output>
+ </operation></binding>
+</screen><para>With rpc style web services the portType names the operation (i.e. the java method on the endpoint)</para><screen xml:space="preserve"> <portType name='EndpointInterface'>
+ <operation name='echo' parameterOrder='String_1'>
+ <input message='tns:EndpointInterface_echo'/>
+ <output message='tns:EndpointInterface_echoResponse'/>
+ </operation></portType>
+</screen><para>Operation parameters are defined by individual message parts.</para><screen xml:space="preserve"> <message name='EndpointInterface_echo'>
+ <part name='String_1' type='xsd:string'/></message><message name='EndpointInterface_echoResponse'>
+ <part name='result' type='xsd:string'/></message>
+</screen><para>Note, there is no complex type in XML schema that could validate the entire SOAP message payload.</para><screen xml:space="preserve">@WebService
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> JSEBean01
+{
+ @WebMethod
+ @WebResult(name="result")
+ <emphasis role="bold">public</emphasis> String echo(@WebParam(name="String_1") String input)
+ {
+ ...
+ }
+}
+</screen><para>The element names of RPC parameters/return values may be defined using the JAX-WS <link linkend="chap_JBossWS-JAX-WSAnnotations">WebParam</link> and <link linkend="chap_JBossWS-JAX-WSAnnotations">WebResult</link> annotations respectively.</para></section>
+<section id="JBossWS-UserGuide_RPCEncoded"><title>RPC/Encoded</title><para>SOAP encodeding style is defined by the infamous <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512">chapter 5</ulink> of the <ulink url="http://www.w3.org/TR/2000/NOTE-SOAP-20000508">SOAP-1.1</ulink> specification. <emphasis role="bold">It has inherent interoperability issues</emphasis> that cannot be fixed. The <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html">Basic Profile-1.0</ulink> prohibits this encoding style in <ulink url="http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html#refinement1...">4.1.7 SOAP encodingStyle Attribute</ulink>.</para><para> JBossWS doesn't support rpc/encoded anymore.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Endpoints"><title>Web Service Endpoints</title><para>JAX-WS simplifies the development model for a web service endpoint a great deal. In short, an endpoint implementation bean is annotated with JAX-WS annotations and deployed to the server. The server automatically generates and publishes the abstract contract (i.e. wsdl+schema) for client consumption. All marshalling/unmarshalling is delegated to JAXB.</para><para> </para><section id="JBossWS-UserGuide_Plain_old_Java_Object_POJO"><title>Plain old Java Object (POJO)</title><para>Let's take a look at simple POJO endpoint implementation. All endpoint associated metadata is provided via JSR-181 annotations</para><screen xml:space="preserve"> @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> JSEBean01
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ ...
+ }
+ }
+</screen><para><emphasis role="bold">The endpoint as a web application</emphasis></para><para>A JAX-WS java service endpoint (JSE) is deployed as a web application.</para><screen xml:space="preserve"> <web-app ...>
+ <servlet>
+ <servlet-name>TestService</servlet-name>
+ <servlet-class>org.jboss.test.ws.jaxws.samples.jsr181pojo.JSEBean01</servlet-class>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>TestService</servlet-name>
+ <url-pattern>/*</url-pattern>
+ </servlet-mapping>
+ </web-app>
+</screen><para><emphasis role="bold">Packaging the endpoint</emphasis></para><para>A JSR-181 java service endpoint (JSE) is packaged as a web application in a *.war file.</para><screen xml:space="preserve"> <war warfile="${build.dir}/libs/jbossws-samples-jsr181pojo.war" webxml="${build.resources.dir}/samples/jsr181pojo/WEB-INF/web.xml">
+ <classes dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181pojo/JSEBean01.class"/>
+ </classes>
+ </war>
+</screen><para>Note, only the endpoint implementation bean and web.xml are required.</para><para><emphasis role="bold">Accessing the generated WSDL</emphasis></para><para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para><screen xml:space="preserve"> http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract off line using jbossw tools. For details of that please see <link linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to WSDL)</link></para><para> </para></section>
+<section id="JBossWS-UserGuide_EJB3_Stateless_Session_Bean_SLSB"><title>EJB3 Stateless Session Bean (SLSB)</title><para>The JAX-WS programming model support the same set of annotations on EJB3 stateless session beans as on <link linkend="JBossWS-UserGuide_Plain_old_Java_Object_POJO">Plain old Java Object (POJO)</link> endpoints. EJB-2.1 endpoints are supported using the JAX-RPC progamming model (with JBossWS-Native only).</para><screen xml:space="preserve"> @Stateless
+ @Remote(EJB3RemoteInterface.class)
+ @RemoteBinding(jndiBinding = "/ejb3/EJB3EndpointInterface")
+
+ @WebService
+ @SOAPBinding(style = SOAPBinding.Style.RPC)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EJB3Bean01 <emphasis role="bold">implements</emphasis> EJB3RemoteInterface
+ {
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String echo(String input)
+ {
+ ...
+ }
+ }
+</screen><para>Above you see an EJB-3.0 stateless session bean that exposes one method both on the remote interface and on and as an endpoint operation.</para><para><emphasis role="bold">Packaging the endpoint</emphasis></para><para>A JSR-181 EJB service endpoint is packaged as an ordinary ejb deployment.</para><screen xml:space="preserve"> <jar jarfile="${build.dir}/libs/jbossws-samples-jsr181ejb.jar">
+ <fileset dir="${build.dir}/classes">
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3Bean01.class"/>
+ <include name="org/jboss/test/ws/samples/jsr181ejb/EJB3RemoteInterface.class"/>
+ </fileset>
+ </jar>
+</screen><para><emphasis role="bold">Accessing the generated WSDL</emphasis></para><para>A successfully deployed service endpoint will show up in the service endpoint manager. This is also where you find the links to the generated wsdl.</para><screen xml:space="preserve"> http://yourhost:8080/jbossws/services
+</screen><para>Note, it is also possible to generate the abstract contract off line using jbossw tools. For details of that please see <link linkend="chap_JBossWS-JAX-WSTools">Bottom-Up (Java to WSDL)</link></para><para> </para></section>
+<section id="JBossWS-UserGuide_Endpoint_Provider"><title>Endpoint Provider</title><para>JAX-WS services typically implement a native Java service endpoint interface (SEI), perhaps mapped from a WSDL port type, either directly or via the use of annotations.</para><para>Java SEIs provide a high level Java-centric abstraction that hides the details of converting between Java objects and their XML representations for use in XML-based messages. However, in some cases it is desirable for services to be able to operate at the XML message level. The Provider interface offers an alternative to SEIs and may be implemented by services wishing to work at the XML message level.</para><para>A Provider based service instances invoke method is called for each message received for the service.</para><screen xml:space="preserve"> @WebServiceProvider(wsdlLocation = "WEB-INF/wsdl/Provider.wsdl")
+ @ServiceMode(value = Service.Mode.PAYLOAD)
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> ProviderBeanPayload <emphasis role="bold">implements</emphasis> Provider<Source>
+ {
+ <emphasis role="bold">public</emphasis> Source invoke(Source req)
+ {
+ // Access the entire request PAYLOAD and return the response PAYLOAD
+ }
+ }
+</screen><para>Note, Service.Mode.PAYLOAD is the default and does not have to be declared explicitly. You can also use Service.Mode.MESSAGE to access the entire SOAP message (i.e. with MESSAGE the Provider can also see SOAP Headers)</para><para>The abstract contract for a provider endpoint cannot be derived/generated automatically. Therefore it is necessary to specify the wsdlLocation with the @WebServiceProvider annotation.</para><para> </para></section>
+<section id="JBossWS-UserGuide_WebServiceContext"><title>WebServiceContext</title><para>The WebServiceContext is treated as an injectable resource that can be set at the time an endpoint is initialized. The WebServiceContext object will then use thread-local information to return the correct information regardless of how many threads are concurrently being used to serve requests addressed to the same endpoint object.</para><screen xml:space="preserve"> @WebService
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EndpointJSE
+ {
+ @Resource
+ WebServiceContext wsCtx;
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String testGetMessageContext()
+ {
+ SOAPMessageContext jaxwsContext = (SOAPMessageContext)wsCtx.getMessageContext();
+ <emphasis role="bold">return</emphasis> jaxwsContext != <emphasis role="bold">null</emphasis> ? "pass" : "fail";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String testGetUserPrincipal()
+ {
+ Principal principal = wsCtx.getUserPrincipal();
+ <emphasis role="bold">return</emphasis> principal.getName();
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">boolean</emphasis> testIsUserInRole(String role)
+ {
+ <emphasis role="bold">return</emphasis> wsCtx.isUserInRole(role);
+ }
+ }
+</screen><para> </para><para> </para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Web_Service_Clients"><title>Web Service Clients</title><section id="JBossWS-UserGuide_Service"><title>Service</title><para><computeroutput>Service</computeroutput> is an abstraction that represents a WSDL service. A WSDL service is a collection of related ports, each of which consists of a port type bound to a particular protocol and available at a particular endpoint address.</para><para>For most clients, you will start with a set of stubs generated from the WSDL. One of these will be the service, and you will create objects of that class in order to work with the service (see "static case" below).</para><section id="JBossWS-UserGuide_Service_Usage"><title>Service Usage</title><para><emphasis role="bold">Static case</emphasis></para><para>Most clients will start with a WSDL file, and generate some stubs using jbossws tools like <emphasis>wsconsume</emphasis>. This usually gives a mass of files, one of which is the top of the tree. This is!
the service implementation class.</para><para>The generated implementation class can be recognised as it will have two public constructors, one with no arguments and one with two arguments, representing the wsdl location (a java.net.URL) and the service name (a javax.xml.namespace.QName) respectively.</para><para>Usually you will use the no-argument constructor. In this case the WSDL location and service name are those found in the WSDL. These are set implicitly from the WebServiceClient annotation that decorates the generated class.</para><para>The following code snippet shows the generated constructors from the generated class:</para><screen xml:space="preserve">// Generated Service Class
+
+@WebServiceClient(name="StockQuoteService", targetNamespace="<ulink url="http://example.com/stocks">http://example.com/stocks</ulink>", wsdlLocation="<ulink url="http://example.com/stocks.wsdl">http://example.com/stocks.wsdl</ulink>")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> StockQuoteService <emphasis role="bold">extends</emphasis> javax.xml.ws.Service
+{
+ <emphasis role="bold">public</emphasis> StockQuoteService()
+ {
+ <emphasis role="bold">super</emphasis>(<emphasis role="bold">new</emphasis> URL("<ulink url="http://example.com/stocks.wsdl">http://example.com/stocks.wsdl</ulink>"), <emphasis role="bold">new</emphasis> QName("<ulink url="http://example.com/stocks">http://example.com/stocks</ulink>", "StockQuoteService"));
+ }
+
+ <emphasis role="bold">public</emphasis> StockQuoteService(String wsdlLocation, QName serviceName)
+ {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ ...
+}
+</screen><para>Section <link linkend="JBossWS-UserGuide_Dynamic_Proxy">Dynamic Proxy</link> explains how to obtain a port from the service and how to invoke an operation on the port. If you need to work with the XML payload directly or with the XML representation of the entire SOAP message, have a look at <link linkend="JBossWS-UserGuide_Dispatch">Dispatch</link>.</para><para><emphasis role="bold">Dynamic case</emphasis></para><para>In the dynamic case, when nothing is generated, a web service client uses <computeroutput>Service.create</computeroutput> to create Service instances, the following code illustrates this process.</para><screen xml:space="preserve"> URL wsdlLocation = <emphasis role="bold">new</emphasis> URL("<ulink url="http://example.org/my.wsdl">http://example.org/my.wsdl</ulink>");
+ QName serviceName = <emphasis role="bold">new</emphasis> QName("<ulink url="http://example.org/sample">http://example.org/sample</ulink>", "MyService");
+ Service service = Service.create(wsdlLocation, serviceName);
+</screen><para> </para><para> </para></section>
+<section id="JBossWS-UserGuide_Handler_Resolver"><title>Handler Resolver</title><para>JAX-WS provides a flexible plug-in framework for message processing modules, known as handlers, that may be used to extend the capabilities of a JAX-WS runtime system. <link linkend="JBossWS-UserGuide_Handler_Framework">Handler Framework</link> describes the handler framework in detail. A Service instance provides access to a HandlerResolver via a pair of getHandlerResolver/setHandlerResolver methods that may be used to configure a set of handlers on a per-service, per-port or per-protocol binding basis.</para><para>When a Service instance is used to create a proxy or a Dispatch instance then the handler resolver currently registered with the service is used to create the required handler chain. Subsequent changes to the handler resolver configured for a Service instance do not affect the handlers on previously created proxies, or Dispatch instances.</para></section>
+<section id="JBossWS-UserGuide_Executor"><title>Executor</title><para>Service instances can be configured with a java.util.concurrent.Executor. The executor will then be used to invoke any asynchronous callbacks requested by the application. The setExecutor and getExecutor methods of Service can be used to modify and retrieve the executor configured for a service.</para></section>
+</section>
+<section id="JBossWS-UserGuide_Dynamic_Proxy"><title>Dynamic Proxy</title><para>You can create an instance of a client proxy using one of getPort methods on the <link linkend="JBossWS-UserGuide_Service">Service</link>.</para><screen xml:space="preserve"> /**
+ * The getPort method returns a proxy. A service client
+ * uses this proxy to invoke operations on the target
+ * service endpoint. The <code>serviceEndpointInterface</code>
+ * specifies the service endpoint interface that is supported by
+ * the created dynamic proxy instance.
+ **/
+ <emphasis role="bold">public</emphasis> <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+
+ /**
+ * The getPort method returns a proxy. The parameter
+ * <code>serviceEndpointInterface</code> specifies the service
+ * endpoint interface that is supported by the returned proxy.
+ * In the implementation of this method, the JAX-WS
+ * runtime system takes the responsibility of selecting a protocol
+ * binding (and a port) and configuring the proxy accordingly.
+ * The returned proxy should not be reconfigured by the client.
+ *
+ **/
+ <emphasis role="bold">public</emphasis> <T> T getPort(Class<T> serviceEndpointInterface)
+ {
+ ...
+ }
+</screen><para>The service endpoint interface (SEI) is usually generated using tools. For details see <link linkend="chap_JBossWS-JAX-WSTools">Top Down (WSDL to Java)</link></para><para>A generated static <ulink url="http://community.jboss.org/Service">Service</ulink> usually also offers typed methods to get ports. These methods also return dynamic proxies that implement the SEI.</para><screen xml:space="preserve">@WebServiceClient(name = "TestEndpointService", targetNamespace = "<ulink url="http://org.jboss.ws/wsref">http://org.jboss.ws/wsref</ulink>",
+ wsdlLocation = "<ulink url="http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl">http://localhost.localdomain:8080/jaxws-samples-webserviceref?wsdl</ulink>")
+
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> TestEndpointService <emphasis role="bold">extends</emphasis> Service
+{
+ ...
+
+ <emphasis role="bold">public</emphasis> TestEndpointService(URL wsdlLocation, QName serviceName) {
+ <emphasis role="bold">super</emphasis>(wsdlLocation, serviceName);
+ }
+
+ @WebEndpoint(name = "TestEndpointPort")
+ <emphasis role="bold">public</emphasis> TestEndpoint getTestEndpointPort()
+ {
+ <emphasis role="bold">return</emphasis> (TestEndpoint)super.getPort(TESTENDPOINTPORT, TestEndpoint.class);
+ }
+}
+</screen><para> </para></section>
+<section id="JBossWS-UserGuide_WebServiceRef"><title>WebServiceRef</title><para>The WebServiceRef annotation is used to declare a reference to a Web service. It follows the resource pattern exemplified by the javax.annotation.Resource annotation in JSR-250.</para><para>There are two uses to the WebServiceRef annotation:</para><orderedlist><listitem><para> To define a reference whose type is a generated service class. In this case, the type and value element will both refer to the generated service class type. Moreover, if the reference type can be inferred by the field/method declaration the annotation is applied to, the type and value elements MAY have the default value (Object.class, that is). If the type cannot be inferred, then at least the type element MUST be present with a non-default value. </para></listitem><listitem><para> To define a reference whose type is a SEI. In this case, the type element MAY be present with its default value if the type of the reference ca!
n be inferred from the annotated field/method declaration, but the value element MUST always be present and refer to a generated service class type (a subtype of javax.xml.ws.Service). The wsdlLocation element, if present, overrides theWSDL location information specified in the WebService annotation of the referenced generated service class. </para></listitem></orderedlist><screen xml:space="preserve"><emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> EJB3Client <emphasis role="bold">implements</emphasis> EJB3Remote
+{
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpointService service4;
+
+ @WebServiceRef
+ <emphasis role="bold">public</emphasis> TestEndpoint port3;
+</screen><para><emphasis role="bold">WebServiceRef Customization</emphasis></para><para>Starting from jboss-5.0.x we offer a number of overrides and extensions to the WebServiceRef annotation. These include</para><itemizedlist><listitem><para> define the port that should be used to resolve a container-managed port </para></listitem><listitem><para> define default Stub property settings for Stub objects </para></listitem><listitem><para> define the URL of a final WSDL document to be used </para></listitem></itemizedlist><para>Example:</para><screen xml:space="preserve"> <service-ref>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <wsdl-override>file:/wsdlRepository/organization-service.wsdl</wsdl-override>
+ </service-ref>
+
+ <service-ref>
+ <service-ref-name>OrganizationService</service-ref-name>
+ <config-name>Secure Client Config</config-name>
+ <config-file>META-INF/jbossws-client-config.xml</config-file>
+ <handler-chain>META-INF/jbossws-client-handlers.xml</handler-chain>
+ </service-ref>
+
+ <service-ref>
+ <service-ref-name>SecureService</service-ref-name>
+ <service-impl-class>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpointService</service-impl-class>
+ <service-qname>{http://org.jboss.ws/wsref}SecureEndpointService</service-qname>
+ <port-component-ref>
+ <service-endpoint-interface>org.jboss.tests.ws.jaxws.webserviceref.SecureEndpoint</service-endpoint-interface>
+ <port-qname>{http://org.jboss.ws/wsref}SecureEndpointPort</port-qname>
+ <stub-property>
+ <prop-name>javax.xml.ws.security.auth.username</prop-name>
+ <prop-value>kermit</prop-value>
+ </stub-property>
+ <stub-property>
+ <prop-name>javax.xml.ws.security.auth.password</prop-name>
+ <prop-value>thefrog</prop-value>
+ </stub-property>
+ </port-component-ref>
+ </service-ref>
+</screen><para>For details please see <emphasis role="bold">service-ref_5_0.dtd</emphasis> in the jboss docs directory.</para><para> </para></section>
+<section id="JBossWS-UserGuide_Dispatch"><title>Dispatch</title><para>XMLWeb Services use XML messages for communication between services and service clients. The higher level JAX-WS APIs are designed to hide the details of converting between Java method invocations and the corresponding XML messages, but in some cases operating at the XML message level is desirable. The Dispatch interface provides support for this mode of interaction.</para><para>Dispatch supports two usage modes, identified by the constants javax.xml.ws.Service.Mode.MESSAGE and javax.xml.ws.Service.Mode.PAYLOAD respectively:</para><para><emphasis role="bold">Message</emphasis> In this mode, client applications work directly with protocol-specific message structures. E.g., when used with a SOAP protocol binding, a client application would work directly with a SOAP message.</para><para><emphasis role="bold">Message Payload</emphasis> In this mode, client applications work with the payload of messages rather!
than the messages themselves. E.g., when used with a SOAP protocol binding, a client application would work with the contents of the SOAP Body rather than the SOAP message as a whole.</para><para>Dispatch is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. Dispatch is a generic class that supports input and output of messages or message payloads of any type.</para><screen xml:space="preserve"> Service service = Service.create(wsdlURL, serviceName);
+ Dispatch dispatch = service.createDispatch(portName, StreamSource.class, Mode.PAYLOAD);
+
+ String payload = "<ns1:ping xmlns:ns1='<ulink url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">http://oneway.samples.jaxws.ws.test.jboss.org/'/</ulink>>";
+ dispatch.invokeOneWay(<emphasis role="bold">new</emphasis> StreamSource(<emphasis role="bold">new</emphasis> StringReader(payload)));
+
+ payload = "<ns1:feedback xmlns:ns1='<ulink url="http://oneway.samples.jaxws.ws.test.jboss.org/'/">http://oneway.samples.jaxws.ws.test.jboss.org/'/</ulink>>";
+ Source retObj = (Source)dispatch.invoke(<emphasis role="bold">new</emphasis> StreamSource(<emphasis role="bold">new</emphasis> StringReader(payload)));
+</screen></section>
+<section id="JBossWS-UserGuide_Asynchronous_Invocations"><title>Asynchronous Invocations</title><para>The BindingProvider interface represents a component that provides a protocol binding for use by clients, it is implemented by proxies and is extended by the Dispatch interface.</para><para>BindingProvider instances may provide asynchronous operation capabilities. When used, asynchronous operation invocations are decoupled from the BindingProvider instance at invocation time such that the response context is not updated when the operation completes. Instead a separate response context is made available using the Response interface.</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> testInvokeAsync() <emphasis role="bold">throws</emphasis> Exception
+ {
+ URL wsdlURL = <emphasis role="bold">new</emphasis> URL("<ulink url="http://">http://</ulink>" + getServerHost() + ":8080/jaxws-samples-asynchronous?wsdl");
+ QName serviceName = <emphasis role="bold">new</emphasis> QName(targetNS, "TestEndpointService");
+ Service service = Service.create(wsdlURL, serviceName);
+ TestEndpoint port = service.getPort(TestEndpoint.class);
+
+ Response response = port.echoAsync("Async");
+
+ // access future
+ String retStr = (String) response.get();
+ assertEquals("Async", retStr);
+ }
+</screen></section>
+<section id="JBossWS-UserGuide_Oneway_Invocations"><title>Oneway Invocations</title><para>@Oneway indicates that the given web method has only an input message and no output. Typically, a oneway method returns the thread of control to the calling application prior to executing the actual business method.</para><screen xml:space="preserve">@WebService (name="PingEndpoint")
+@SOAPBinding(style = SOAPBinding.Style.RPC)
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> PingEndpointImpl
+{
+ <emphasis role="bold">private</emphasis> <emphasis role="bold">static</emphasis> String feedback;
+
+ @WebMethod
+ @Oneway
+ <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> ping()
+ {
+ log.info("ping");
+ feedback = "ok";
+ }
+
+ @WebMethod
+ <emphasis role="bold">public</emphasis> String feedback()
+ {
+ log.info("feedback");
+ <emphasis role="bold">return</emphasis> feedback;
+ }
+}
+</screen></section>
+<section id="JBossWS-UserGuide_Oneway_Invocations_697545"><title>Timeout Configuration</title><para>There are two properties to configure the http connection timeout and client receive time out:</para><screen xml:space="preserve"> public void testConfigureTimeout() throws Exception { //Set timeout until a connection is established ((BindingProvider) port).getRequestContext(). put("javax.xml.ws.client.connectionTimeout", "6000"); //Set timeout until the response is received ((BindingProvider) port).getRequestContext(). put("javax.xml.ws.client.receiveTimeout", "1000"); port.echo("testTimeout"); }
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Common_API"><title>Common API</title><para>This sections describes concepts that apply equally to <link linkend="JBossWS-UserGuide_Web_Service_Endpoints">Web Service Endpoints</link> and <link linkend="JBossWS-UserGuide_Web_Service_Clients">Web Service Clients</link>.</para><section id="JBossWS-UserGuide_Handler_Framework"><title>Handler Framework</title><para>The handler framework is implemented by a JAX-WS protocol binding in both client and server side runtimes. Proxies, and Dispatch instances, known collectively as binding providers, each use protocol bindings to bind their abstract functionality to specific protocols.</para><para>Client and server-side handlers are organized into an ordered list known as a handler chain. The handlers within a handler chain are invoked each time a message is sent or received. Inbound messages are processed by handlers prior to binding provider processing. Outbound messages are processed by handlers after a!
ny binding provider processing.</para><para>Handlers are invoked with a message context that provides methods to access and modify inbound and outbound messages and to manage a set of properties. Message context properties may be used to facilitate communication between individual handlers and between handlers and client and service implementations. Different types of handlers are invoked with different types of message context.</para><section id="JBossWS-UserGuide_Logical_Handler"><title>Logical Handler</title><para>Handlers that only operate on message context properties and message payloads. Logical handlers are protocol agnostic and are unable to affect protocol specific parts of a message. Logical handlers are handlers that implement javax.xml.ws.handler.LogicalHandler.</para></section>
+<section id="JBossWS-UserGuide_Protocol_Handler"><title>Protocol Handler</title><para>Handlers that operate on message context properties and protocol specific messages. Protocol handlers are specific to a particular protocol and may access and change protocol specific aspects of a message. Protocol handlers are handlers that implement any interface derived from javax.xml.ws.handler.Handler except javax.xml.ws.handler.LogicalHandler.</para></section>
+<section id="JBossWS-UserGuide_Service_endpoint_handlers"><title>Service endpoint handlers</title><para>On the service endpoint, handlers are defined using the @HandlerChain annotation.</para><screen xml:space="preserve">@WebService
+@HandlerChain(file = "jaxws-server-source-handlers.xml")
+<emphasis role="bold">public</emphasis> <emphasis role="bold">class</emphasis> SOAPEndpointSourceImpl
+{
+ ...
+}
+</screen><para>The location of the handler chain file supports 2 formats</para><para>1. An absolute java.net.URL in externalForm. (ex: <ulink url="http://myhandlers.foo.com/handlerfile1.xml">http://myhandlers.foo.com/handlerfile1.xml</ulink>)</para><para>2. A relative path from the source file or class file. (ex: bar/handlerfile1.xml)</para></section>
+<section id="JBossWS-UserGuide_Service_client_handlers"><title>Service client handlers</title><para>On the client side, handler can be configured using the @HandlerChain annotation on the SEI or dynamically using the API.</para><screen xml:space="preserve"> Service service = Service.create(wsdlURL, serviceName);
+ Endpoint port = (Endpoint)service.getPort(Endpoint.class);
+
+ BindingProvider bindingProvider = (BindingProvider)port;
+ List<Handler> handlerChain = <emphasis role="bold">new</emphasis> ArrayList<Handler>();
+ handlerChain.add(<emphasis role="bold">new</emphasis> LogHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis> AuthorizationHandler());
+ handlerChain.add(<emphasis role="bold">new</emphasis> RoutingHandler());
+ bindingProvider.getBinding().setHandlerChain(handlerChain); // important!
+</screen></section>
+</section>
+<section id="JBossWS-UserGuide_Message_Context"><title>Message Context</title><para>MessageContext is the super interface for all JAX-WS message contexts. It extends Map<String,Object> with additional methods and constants to manage a set of properties that enable handlers in a handler chain to share processing related state. For example, a handler may use the put method to insert a property in the message context that one or more other handlers in the handler chain may subsequently obtain via the get method.</para><para>Properties are scoped as either APPLICATION or HANDLER. All properties are available to all handlers for an instance of an MEP on a particular endpoint. E.g., if a logical handler puts a property in the message context, that property will also be available to any protocol handlers in the chain during the execution of an MEP instance. APPLICATION scoped properties are also made available to client applications (see section 4.2.1) and service endpoint i!
mplementations. The defaultscope for a property is HANDLER.</para><section id="JBossWS-UserGuide_Logical_Message_Context"><title>Logical Message Context</title><para><link linkend="JBossWS-UserGuide_Logical_Handler">Logical Handlers</link> are passed a message context of type LogicalMessageContext when invoked. LogicalMessageContext extends MessageContext with methods to obtain and modify the message payload, it does not provide access to the protocol specific aspects of amessage. A protocol binding defines what component of a message are available via a logical message context. The SOAP binding defines that a logical handler deployed in a SOAP binding can access the contents of the SOAP body but not the SOAP headers whereas the XML/HTTP binding defines that a logical handler can access the entire XML payload of a message.</para></section>
+<section id="JBossWS-UserGuide_SOAP_Message_Context"><title>SOAP Message Context</title><para>SOAP handlers are passed a SOAPMessageContext when invoked. SOAPMessageContext extends MessageContext with methods to obtain and modify the SOAP message payload.</para></section>
+</section>
+<section id="JBossWS-UserGuide_Fault_Handling"><title>Fault Handling</title><para>An implementation may thow a SOAPFaultException</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> throwSoapFaultException()
+ {
+ SOAPFactory factory = SOAPFactory.newInstance();
+ SOAPFault fault = factory.createFault("this is a fault string!", <emphasis role="bold">new</emphasis> QName("<ulink url="http://foo">http://foo</ulink>", "FooCode"));
+ fault.setFaultActor("mr.actor");
+ fault.addDetail().addChildElement("test");
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> SOAPFaultException(fault);
+ }
+</screen><para>or an application specific user exception</para><screen xml:space="preserve"> <emphasis role="bold">public</emphasis> <emphasis role="bold">void</emphasis> throwApplicationException() <emphasis role="bold">throws</emphasis> UserException
+ {
+ <emphasis role="bold">throw</emphasis> <emphasis role="bold">new</emphasis> UserException("validation", 123, "Some validation error");
+ }
+</screen><note><para><para><emphasis role="bold">Note</emphasis></para><para>In case of the latter JBossWS generates the required fault wrapper beans at runtime if they are not part of the deployment</para><para> </para></para></note>
+</section>
+<section id="JBossWS-UserGuide_JBossWS_Extensions"><title>JBossWS Extensions</title><para>This section describes propriatary JBoss extensions to JAX-WS, that works with all the supported stacks.</para><para> </para><section id="JBossWS-UserGuide_Proprietary_Annotations"><title>Proprietary Annotations</title><para>For the set of standard annotations, please have a look at <link linkend="chap_JBossWS-JAX-WSAnnotations">JAX-WS_Annotations</link>.</para><para> </para><section id="JBossWS-UserGuide_WebContext"><title>WebContext</title><screen xml:space="preserve">/**
+ * Provides web context specific meta data to EJB based web service endpoints.
+ *
+ * @author <ulink url="mailto:thomas.diesler@jboss.org">thomas.diesler(a)jboss.org</ulink>
+ * @since 26-Apr-2005
+ */
+@Retention(value = RetentionPolicy.RUNTIME)
+@Target(value = { ElementType.TYPE })
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> WebContext {
+
+ /**
+ * The contextRoot element specifies the context root that the web service endpoint is deployed to.
+ * If it is not specified it will be derived from the deployment short name.
+ *
+ * Applies to server side port components only.
+ */
+ String contextRoot() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The virtual hosts that the web service endpoint is deployed to.
+ *
+ * Applies to server side port components only.
+ */
+ String[] virtualHosts() <emphasis role="bold">default</emphasis> {};
+
+ /**
+ * Relative path that is appended to the contextRoot to form fully qualified
+ * endpoint address for the web service endpoint.
+ *
+ * Applies to server side port components only.
+ */
+ String urlPattern() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The authMethod is used to configure the authentication mechanism for the web service.
+ * As a prerequisite to gaining access to any web service which are protected by an authorization
+ * constraint, a user must have authenticated using the configured mechanism.
+ *
+ * Legal values for this element are "BASIC", or "CLIENT-CERT".
+ */
+ String authMethod() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * The transportGuarantee specifies that the communication
+ * between client and server should be NONE, INTEGRAL, or
+ * CONFIDENTIAL. NONE means that the application does not require any
+ * transport guarantees. A value of INTEGRAL means that the application
+ * requires that the data sent between the client and server be sent in
+ * such a way that it can't be changed in transit. CONFIDENTIAL means
+ * that the application requires that the data be transmitted in a
+ * fashion that prevents other entities from observing the contents of
+ * the transmission. In most cases, the presence of the INTEGRAL or
+ * CONFIDENTIAL flag will indicate that the use of SSL is required.
+ */
+ String transportGuarantee() <emphasis role="bold">default</emphasis> "";
+
+ /**
+ * A secure endpoint does not secure wsdl access by default.
+ * Explicitly setting secureWSDLAccess overrides this behaviour.
+ *
+ * Protect access to WSDL. See <ulink url="http://jira.jboss.org/jira/browse/JBWS-723">http://jira.jboss.org/jira/browse/JBWS-723</ulink>
+ */
+ <emphasis role="bold">boolean</emphasis> secureWSDLAccess() <emphasis role="bold">default</emphasis> <emphasis role="bold">false</emphasis>;
+}
+</screen></section>
+<section id="JBossWS-UserGuide_SecurityDomain"><title>SecurityDomain</title><screen xml:space="preserve">/**
+ * Annotation for specifying the JBoss security domain for an EJB
+ *
+ * @author <a href="mailto:<ulink url="mailto:bill@jboss.org">bill(a)jboss.org</ulink>">Bill Burke</a>
+ **/
+(a)Target(ElementType.TYPE) @Retention(RetentionPolicy.RUNTIME)
+<emphasis role="bold">public</emphasis> @<emphasis role="bold">interface</emphasis> SecurityDomain
+{
+ /**
+ * The required name for the security domain.
+ *
+ * Do not use the JNDI name
+ *
+ * Good: "MyDomain"
+ * Bad: "java:/jaas/MyDomain"
+ */
+ String value();
+
+ /**
+ * The name for the unauthenticated pricipal
+ */
+ String unauthenticatedPrincipal() <emphasis role="bold">default</emphasis> "";
+</screen></section></section>
+</section>
+<section id="JBossWS-UserGuide_JAXB_Introductions"><title>JAXB Introductions</title><para>As Kohsuke Kawaguchi writes on <ulink url="http://weblogs.java.net/blog/kohsuke/archive/2007/07/binding_3rd_par.html">his blog</ulink>, one common complaint from the JAXB users is the lack of support for binding 3rd party classes. The scenario is this you are trying to annotate your classes with JAXB annotations to make it XML bindable, but some of the classes are coming from libraries and JDK, and thus you cannot put necessary JAXB annotations on it.</para><para>To solve this JAXB has been designed to provide hooks for programmatic introduction of annotations to the runtime.</para><para>This is currently leveraged by the JBoss JAXB Introductions project, using which users can define annotations in XML and make JAXB see those as if those were in the class files (perhaps coming from 3rd party libraries).</para><para> </para><para>JAXB Introductions are currently supported in JBossWS-N!
ative (server side only, since 3.0.2.GA) and JBossWS-CXF (both server and client side, since 3.2.1.GA).</para><para>Take a look at the <ulink url="http://community.jboss.org/docs/DOC-10075">JAXB Introductions page</ulink> on the wiki and at the examples in the sources.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Tools"><title>Tools</title><para>The JBossWS Web Service Framework provides unified tooling for all the supported stacks. This currently includes common JAX-WS tools for both contract-first and code-first development and common management tools.</para><section id="JBossWS-UserGuide_JAXWS_tools"><title>JAX-WS tools</title><para>Please refer to <link linkend="chap_JBossWS-JAX-WSTools">JBossWS_JAX-WS_Tools</link> for details. This covers directions on web service contract generation (bottom-up development) and consumption (top-down and client development).</para></section>
+<section id="JBossWS-UserGuide_Management_tools"><title>Management tools</title><para>JBoss and its web service framework come with some tools allowing WS endpoint management.</para><para>Please refer the <link linkend="chap_JBossWS-Endpointmanagement">Endpoint management</link> page for an overview of the available tools. In particular the <link linkend="chap_JBossWS-Recordsmanagement">JBossWS - Records management</link> gives administrators a means of performing custom analysis of their web service traffic as well as exporting communication logs.</para></section>
+<section id="JBossWS-UserGuide_Web_Service_console"><title>Web Service console</title><para>All supported stacks provide a web console for getting the list of the endpoints currently deployed on a given host as well as basic metrics regarding invocations to them. The console is available at <ulink url="http://localhost:8080/jbossws/services">http://localhost:8080/jbossws/services</ulink> assuming your application server is currently bound to localhost:8080.</para><para> </para></section>
+</section>
+<section id="JBossWS-UserGuide_Configuration"><title>Configuration</title><section id="JBossWS-UserGuide_Address_rewrite"><title>Address rewrite</title><para>JBossWS allows users to configure the soap:address attribute in the wsdl contract of deployed services as well as wsdl address in the web service console. [due to a known issue this does not currently work with JBossWS-Metro, see: <ulink url="https://jira.jboss.org/jira/browse/JBWS-2462">JBWS-2462</ulink>]</para><para> </para><para><emphasis role="bold">Server configuration options</emphasis></para><para> </para><para>There're few attributes in the jbossws deployers configuration (currently in jbossws.deployer/META-INF/stack-agnostic-jboss-beans.xml) controlling the way the soap:address attribute in the wsdl is rewritten.</para><screen xml:space="preserve"><bean name="WSServerConfig" class="org.jboss.webservices.integration.config.ServerConfigImpl">
+ <property name="mbeanServer"><inject bean="WSMBeanServerLocator" property="mbeanServer"/></property>
+
+ <property name="webServiceHost">${jboss.bind.address}</property>
+ <property name="modifySOAPAddress">true</property>
+
+ <!--
+ <property name="webServiceSecurePort">8443</property>
+ <property name="webServicePort">8080</property>
+ -->
+ </bean>
+</screen><para> </para><para>If the content of <emphasis><soap:address></emphasis> in the wsdl is a valid URL, JBossWS will not rewrite it unless <emphasis>modifySOAPAddress</emphasis> is true. If the content of <emphasis><soap:address></emphasis> is not a valid URL instead, JBossWS will always rewrite it using the attribute values given below. Please note that the variable <emphasis>${jboss.bind.address}</emphasis> can be used to set the address which the application is bound to at each startup.</para><para> </para><para>The webServiceSecurePort and webServicePort attributes are used to explicitly define the ports to be used for rewriting the SOAP address. If these attributes are not set, the ports will be identified by querying the list of installed connectors. If multiple connectors are found the port of the first connector is used.</para><para> </para><para><emphasis role="bold">Dynamic rewrite</emphasis></para><para> </para><para>When the application se!
rver is bound to multiple addresses or non-trivial real-world network architectures cause request for different external addresses to hit the same endpoint, a static rewrite of the soap:address may not be enough. JBossWS allows for both the soap:address in the wsdl and the wsdl address in the console to be rewritten with the host use in the client request. This way, users always get the right wsdl address assuming they're connecting to an instance having the endpoint they're looking for. To trigger this behaviour, the <emphasis role="bold">jbossws.undefined.host</emphasis> value has to be specified for the <emphasis>webServiceHost</emphasis> attribute.</para><screen xml:space="preserve"><property name="webServiceHost">jbossws.undefined.host</property>
+<property name="modifySOAPAddress">true</property></screen><para> </para><para>Of course, when a confidential transport address is required, the addresses are always rewritten using https protocol and the port currently configured for the https/ssl connector.</para></section>
+</section></section></chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-wsconsume.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-wsconsume.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-wsconsume.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsconsume"><title>JBossWS-wsconsume</title><para>wsconsume is a command line tool and ant task that "consumes" the abstract contract (WSDL file) and produces portable JAX-WS service and client artifacts. For a more detailed overview, see <ulink url="http://community.jboss.org/docs/DOC-13544#TopDown_Using_wsconsume">"Using wsconsume"</ulink>.</para><para/><section id="JBossWS-wsconsume_Command_Line_Tool"><title>Command Line Tool</title><para>The command line tool has the following usage:</para><screen xml:space="preserve">usage: wsconsume [options] <wsdl-url>
+options:
+ -h, --help Show this help message
+ -b, --binding=<file> One or more JAX-WS or JAXB binding files
+ -k, --keep Keep/Generate Java source
+ -c --catalog=<file> Oasis XML Catalog file for entity resolution
+ -p --package=<name> The target package for generated source
+ -w --wsdlLocation=<loc> Value to use for @WebServiceClient.wsdlLocation
+ -o, --output=<directory> The directory to put generated artifacts
+ -s, --source=<directory> The directory to put Java source
+ -t, --target=<2.0|2.1|2.2> The JAX-WS specification target
+ -q, --quiet Be somewhat more quiet
+ -v, --verbose Show full exception stack traces
+ -l, --load-consumer Load the consumer and exit (debug utility)
+ -e, --extension Enable SOAP 1.2 binding extension
+ -a, --additionalHeaders Enables processing of implicit SOAP headers</screen><para> </para><para><emphasis role="bold">Note</emphasis> : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.</para><section id="JBossWS-wsconsume_Examples"><title>Examples</title><para>Generate artifacts in Java class form only:</para><screen xml:space="preserve">wsconsume Example.wsdl
+</screen><para>Generate source and class files:</para><screen xml:space="preserve">wsconsume -k Example.wsdl
+</screen><para>Generate source and class files in a custom directory:</para><screen xml:space="preserve">wsconsume -k -o custom Example.wsdl
+</screen><para>Generate source and class files in the org.foo package:</para><screen xml:space="preserve">wsconsume -k -p org.foo Example.wsdl
+</screen><para>Generate source and class files using multiple binding files:</para><screen xml:space="preserve">wsconsume -k -b wsdl-binding.xml -b schema1-binding.xml -b schema2-binding.xml</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Maven_Plugin"><title>Maven Plugin</title><para>The wsconsume tools is included in the <emphasis role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis>wsconsume</emphasis> and <emphasis>wsconsume-test</emphasis>, which basically do the same during different maven build phases (the former triggers the sources generation during <emphasis>generate-sources</emphasis> phase, the latter during the <emphasis>generate-test-sources</emphasis> one).</para><para>The wsconsume plugin has the following parameters:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default </entry></row></thead><tbody><row><entry>bindingFiles</entry><entry>JAXWS or JAXB binding file</entry><entry>true</entry></row><row><entry>classpath!
Elements</entry><entry><para>Each classpathElement provides a</para><para>library file to be added to classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>catalog</entry><entry>Oasis XML Catalog file for entity resolution</entry><entry>none</entry></row><row><entry>targetPackage</entry><entry>The target Java package for generated code.</entry><entry>generated</entry></row><row><entry>bindingFiles</entry><entry>One or more JAX-WS or JAXB binding file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value to use for @WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>outputDirectory</entry><entry>The output directory for generated artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>sourceDirectory</entry><entry!
>The output directory for Java source.</entry><entry>${project!
.build.d
irectory}/wsconsume/java</entry></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</entry><entry>false</entry></row><row><entry>wsdls</entry><entry>The WSDL files or URLs to consume</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsconsume_Examples_187752"><title>Examples</title><para>You can use wsconsume in your own project build simply referencing the <emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in your pom.xml file.</para><para>The following example makes the plugin consume the test.wsdl file and generate SEI and wrappers' java sources. The generated sources are then compiled together with the other project classes.</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>You can also specify multiple wsdl files, as well as force the target package, enable SOAP 1.2 binding and turn the tool's verbose mode on:</para><para> </para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ <wsdl>${basedir}/test2.wsdl</wsdl>
+ </wsdls>
+ <targetPackage>foo.bar</targetPackage>
+ <extension>true</extension>
+ <verbose>true</verbose>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>Finally, if the wsconsume invocation is required for consuming a wsdl to be used in your testsuite only, you might want to use the <emphasis>wsconsume-test</emphasis> goal as follows:</para><para> </para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>1.0.0.GA</version>
+ <configuration>
+ <wsdls>
+ <wsdl>${basedir}/test.wsdl</wsdl>
+ </wsdls>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsconsume-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen></section>
+</section>
+<section id="JBossWS-wsconsume_Ant_Task"><title>Ant Task</title><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSConsumeTask. Also put streamBuffer.jar and stax-ex.jar in the classpath of the ant task to generate the appropriate artefacts. Both jar files are in the jbossws lib directory. For jbossws-native-2.0.3.GA these files are not automatically installed if you run jboss-deployXX.</emphasis></para></para></note><para>The wsconsume ant task has the following attributes:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Attribute</entry><entry>Description</entry><entry>Default </entry></row></thead><tbody><row><entry>fork</entry><entry>Whether or not to run the generation task in a separate VM.</entry><entry>true</entry></row><row><entry>keep</e!
ntry><entry>Keep/Enable Java source code generation.</entry><entry>false</entry></row><row><entry>catalog</entry><entry>Oasis XML Catalog file for entity resolution</entry><entry>none</entry></row><row><entry>package</entry><entry>The target Java package for generated code.</entry><entry>generated</entry></row><row><entry>binding</entry><entry>A JAX-WS or JAXB binding file</entry><entry>none</entry></row><row><entry>wsdlLocation</entry><entry>Value to use for @WebServiceClient.wsdlLocation</entry><entry>generated</entry></row><row><entry>destdir</entry><entry>The output directory for generated artifacts.</entry><entry>"output"</entry></row><row><entry>sourcedestdir</entry><entry>The output directory for Java source.</entry><entry>value of destdir</entry></row><row><entry>target</entry><entry>The JAX-WS specification target. Allowed values are 2.0, 2.1 and 2.2</entry><entry/></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</en!
try><entry>false</entry></row><row><entry>wsdl</entry><entry>T!
he WSDL
file or URL</entry><entry>n/a</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry><para>false</para></entry></row><row><entry>additionalHeaders</entry><entry>Enables processing of implicit SOAP headers</entry><entry>false</entry></row></tbody></tgroup></informaltable><para><emphasis role="bold">Note</emphasis> : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.</para><para> </para><para>Also, the following nested elements are supported:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry>Element</entry><entry>Des!
cription</entry><entry>Default </entry></row></thead><tbody><row><entry>binding</entry><entry>A JAXWS or JAXB binding file</entry><entry>none</entry></row><row><entry>jvmarg</entry><entry>Allows setting of custom jvm arguments</entry><entry/></row></tbody></tgroup></informaltable><para> </para><section id="JBossWS-wsconsume_Examples_184359"><title>Examples</title><para>Generate JAX-WS source and classes in a separate JVM with separate directories, a custom wsdl location attribute, and a list of binding files from foo.wsdl:</para><screen xml:space="preserve"><wsconsume
+ fork="true"
+ verbose="true"
+ destdir="output"
+ sourcedestdir="gen-src"
+ keep="true"
+ wsdllocation="handEdited.wsdl"
+ wsdl="foo.wsdl">
+ <binding dir="binding-files" includes="*.xml" excludes="bad.xml"/>
+</wsconsume></screen></section>
+</section>
+<section id="JBossWS-wsconsume_Related_information"><title>Related information</title><itemizedlist><listitem><para> <ulink url="http://java.sun.com/webservices/docs/2.0/jaxws/customizations.html">JAX-WS binding customization</ulink> </para></listitem></itemizedlist></section>
+</chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-wsprovide.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-wsprovide.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-wsprovide.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsprovide"><title>JBossWS-wsprovide</title><para>wsprovide is a command line tool and ant task that generates portable JAX-WS artifacts for a service endpoint implementation. It also has the option to "provide" the abstract contract for offline usage. See <ulink url="http://community.jboss.org/docs/DOC-13544#BottomUp_Using_wsprovide">"Using wsprovide"</ulink> for a detailed walk-through.</para><para/><section id="JBossWS-wsprovide_Command_Line_Tool"><title>Command Line Tool</title><para>The command line tool has the following usage:</para><screen xml:space="preserve"> usage: wsprovide [options] <endpoint class name>
+ options:
+ -h, --help Show this help message
+ -k, --keep Keep/Generate Java source
+ -w, --wsdl Enable WSDL file generation
+ -c. --classpath=<path< The classpath that contains the endpoint
+ -o, --output=<directory> The directory to put generated artifacts
+ -r, --resource=<directory> The directory to put resource artifacts
+ -s, --source=<directory> The directory to put Java source
+ -e, --extension Enable SOAP 1.2 binding extension
+ -q, --quiet Be somewhat more quiet
+ -t, --show-traces Show full exception stack traces</screen><section id="JBossWS-wsprovide_Examples"><title>Examples</title><para>Generating wrapper classes for portable artifacts in the "generated" directory:</para><screen xml:space="preserve">wsprovide -o generated foo.Endpoint
+</screen><para>Generating wrapper classes and WSDL in the "generated" directory</para><screen xml:space="preserve">wsprovide -o generated -w foo.Endpoint
+</screen><para>Using an endpoint that references other jars</para><screen xml:space="preserve">wsprovide -o generated -c application1.jar:application2.jar foo.Endpoint</screen></section>
+</section>
+<section id="JBossWS-wsprovide_Maven_Plugin"><title>Maven Plugin</title><para>The wsprovide tools is included in the <emphasis role="bold">org.jboss.ws.plugins:maven-jaxws-tools-plugin</emphasis> plugin. The plugin has two goals for running the tool, <emphasis>wsprovide</emphasis> and <emphasis>wsprovide-test</emphasis>, which basically do the same during different maven build phases (the former triggers the sources generation during <emphasis>process-classes</emphasis> phase, the latter during the <emphasis>process-test-classes</emphasis> one).</para><para>The wsprovide plugin has the following parameters:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry> Attribute </entry><entry> Description </entry><entry> Default </entry></row></thead><tbody><row><entry>testClasspathElements</entry><entry><para>Each classpathElement provides a</para><para>library file to b!
e added to classpath</para></entry><entry><para>${project.compileClasspathElements}</para><para>or</para><para>${project.testClasspathElements}</para></entry></row><row><entry>outputDirectory</entry><entry>The output directory for generated artifacts.</entry><entry><para>${project.build.outputDirectory}</para><para>or</para><para>${project.build.testOutputDirectory}</para></entry></row><row><entry>resourceDirectory</entry><entry>The output directory for resource artifacts (WSDL/XSD).</entry><entry>${project.build.directory}/wsprovide/resources</entry></row><row><entry>sourceDirectory</entry><entry>The output directory for Java source.</entry><entry>${project.build.directory}/wsprovide/java</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row><row><entry>generateWsdl</entry><entry>Whether or not to generate WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables more informational output!
about command progress.</entry><entry>false</entry></row><row!
><entry>
<emphasis role="bold">endpointClass</emphasis></entry><entry><emphasis role="bold">Service Endpoint Implementation.</emphasis></entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsprovide_Examples_147019"><title>Examples</title><para>You can use wsprovide in your own project build simply referencing the <emphasis>maven-jaxws-tools-plugin</emphasis> in the configured plugins in your pom.xml file.</para><para>The following example makes the plugin provide the wsdl file and artifact sources for the specified endpoint class:</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>@pom.version(a)</version>
+ <configuration>
+ <verbose>true</verbose>
+ <endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para><para>The following example does the same, but is meant for use in your own testsuite:</para><screen xml:space="preserve"><build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.ws.plugins</groupId>
+ <artifactId>maven-jaxws-tools-plugin</artifactId>
+ <version>@pom.version(a)</version>
+ <configuration>
+ <verbose>true</verbose>
+ <endpointClass>org.jboss.test.ws.plugins.tools.wsprovide.TestEndpoint2</endpointClass>
+ <generateWsdl>true</generateWsdl>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>wsprovide-test</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+</build>
+</screen><para> </para></section>
+</section>
+<section id="JBossWS-wsprovide_Ant_Task"><title>Ant Task</title><note><para><para><emphasis><emphasis role="bold">Note</emphasis></emphasis></para><para><emphasis>With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSProvideTask</emphasis></para></para></note><para>The wsprovide ant task has the following attributes:</para><informaltable><tgroup cols="3"><colspec colnum="1" colname="col1"/><colspec colnum="2" colname="col2"/><colspec colnum="3" colname="col3"/><thead><row><entry> Attribute </entry><entry> Description </entry><entry> Default </entry></row></thead><tbody><row><entry>fork</entry><entry>Whether or not to run the generation task in a separate VM.</entry><entry>true</entry></row><row><entry>keep</entry><entry>Keep/Enable Java source code generation.</entry><entry>false</entry></row><row><entry>destdir</entry><entry>The output directory for generated artifacts.</entry><entry>"output"</entry></row><row><entry>resourcedestdir</entry><entry>The output dir!
ectory for resource artifacts (WSDL/XSD).</entry><entry>value of destdir</entry></row><row><entry>sourcedestdir</entry><entry>The output directory for Java source.</entry><entry>value of destdir</entry></row><row><entry>extension</entry><entry>Enable SOAP 1.2 binding extension.</entry><entry>false</entry></row><row><entry>genwsdl</entry><entry>Whether or not to generate WSDL.</entry><entry>false</entry></row><row><entry>verbose</entry><entry>Enables more informational output about command progress.</entry><entry>false</entry></row><row><entry><emphasis role="bold">sei</emphasis></entry><entry><emphasis role="bold">Service Endpoint Implementation.</emphasis></entry></row><row><entry>classpath</entry><entry>The classpath that contains the service endpoint implementation.</entry><entry>"."</entry></row></tbody></tgroup></informaltable><section id="JBossWS-wsprovide_Examples_860945"><title>Examples</title><para>Executing wsprovide in verbose mode with separate output directorie!
s for source, resources, and classes:</para><screen xml:space=!
"preserv
e"><target name="test-wsproivde" depends="init">
+ <taskdef name="wsprovide" classname="org.jboss.wsf.spi.tools.ant.WSProvideTask">
+ <classpath refid="core.classpath"/>
+ </taskdef>
+ <wsprovide
+ fork="false"
+ keep="true"
+ destdir="out"
+ resourcedestdir="out-resource"
+ sourcedestdir="out-source"
+ genwsdl="true"
+ verbose="true"
+ sei="org.jboss.test.ws.jaxws.jsr181.soapbinding.DocWrappedServiceImpl">
+ <classpath>
+ <pathelement path="${tests.output.dir}/classes"/>
+ </classpath>
+ </wsprovide>
+</target>
+</screen></section>
+</section></chapter>
\ No newline at end of file
Added: stack/cxf/trunk/src/main/doc/JBossWS-wsrunclient.xml
===================================================================
--- stack/cxf/trunk/src/main/doc/JBossWS-wsrunclient.xml (rev 0)
+++ stack/cxf/trunk/src/main/doc/JBossWS-wsrunclient.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?><chapter id="chap_JBossWS-wsrunclient"><title>JBossWS-wsrunclient</title><para>wsrunclient is a command line tool that invokes a JBossWS JAX-WS Web Service client. It builds the correct classpath and endorsed libs for you. Feel free to use the code for this script to make your own shell scripts. It is open source after all.</para><section><title>Usage</title><screen xml:space="preserve"> wsrunclient [-classpath <additional class path>] <java-main-class> [arguments...]
+</screen></section>
+<section><title>Examples</title><para>Invoking a standalone JAX-WS client:</para><screen xml:space="preserve">wsrunclient echo.EchoClient</screen><para>Invoking a standalone JAX-WS client that uses external jars:</para><screen xml:space="preserve">wsrunclient -classpath jar1.jar:jar2.jar echo.EchoClient
+
+</screen></section>
+</chapter>
\ No newline at end of file
Modified: stack/cxf/trunk/src/main/scripts/assembly-bin-dist.xml
===================================================================
--- stack/cxf/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 14:28:01 UTC (rev 13199)
+++ stack/cxf/trunk/src/main/scripts/assembly-bin-dist.xml 2010-11-02 18:00:03 UTC (rev 13200)
@@ -55,6 +55,10 @@
<include>JBossORG-EULA.txt</include>
</includes>
</fileSet>
+ <fileSet>
+ <directory>target/docbook/publish</directory>
+ <outputDirectory>jbossws-cxf-bin-dist/docs</outputDirectory>
+ </fileSet>
<!-- deploy -->
<fileSet>
<directory>target/assembly/deploy-artifacts</directory>
14 years, 4 months
- 1
- 0
JBossWS SVN: r13199 - projects.
by jbossws-commits＠lists.jboss.org
Author: alessio.soldano(a)jboss.com
Date: 2010-11-02 10:28:01 -0400 (Tue, 02 Nov 2010)
New Revision: 13199
Added:
projects/docbuilder-legacy/
Removed:
projects/docbuilder/
Log:
Renaming lgacy docbuilder dir
Copied: projects/docbuilder-legacy (from rev 13198, projects/docbuilder)
14 years, 4 months
- 1
- 0