Transcription
Artix 5.6.3DeploymentGuide: Java
Micro FocusThe Lawn22-30 Old Bath RoadNewbury, Berkshire RG14 1QNUKhttp://www.microfocus.comC opyright Micro Focus 2015. All rights reserved.MIC RO FOCUS, the Micro Focus logo and Micro Focus Licensing are trademarks orregistered trademarks of Micro Focus IP Development Limited or its subsidiaries oraffiliated companies in the United States, United Kingdom and other countries.All other marks are the property of their respective owners.2015-03-12
ContentsPreface. vWhat is Covered in This Book . vWho Should Read This Book . vOrganization of this Guide . vThe Artix Documentation Library . viFurther Information and Product Support . viInformation We Need. viContact information .viiArtix for Java Configuration Overview .1Artix Conf iguration Files . 1Making Your Conf iguration F ile Available . 3Setting Up Your Environment .5Using the Artix Environment Script. 5Artix for Java Env ironment Variables . 5Customizing your Env ironment Script . 6Configuring Artix Endpoints.9Configuring Service Providers. 9Using the jaxws:endpoint Element . 9Using the jaxws:server Element. 13Adding Functionality to Service Providers. 16Configuring Consumer Endpoints . 18Basic Configuration Properties . 18Artix for Java Logging . 61Overv iew of Artix for Java Logging . 61Simple Example of Using Logging . 62Default logging.propertiesFile . 63Configuring Logging Levels . 65Enabling Logging at the Command Line . 66Logging for Subsystems and Serv ices . 66Logging Message Content . 68Deploying to the Spring Container . 81Introduction . 81Running the Spring Container . 82Deploying an Artix Endpoint . 83Managing the Container using the JMX Console . 86Managing the Container using the Web Service Interface . 88Spring Container Definition File . 89Running Multiple Containers on Same Host . 91Artix Deployment Guide: Java iii
Deploying to a Servlet Container . 99Introduction .99Configuring the Servlet Container . 100Using the CXF Servlet. 101Using a Custom Servlet . 104Using the Spring Context Listener . 107Deploying WS-Addressing.110Introduction to WS-Addressing . 110WS-Addressing Interceptors . 110Enabling WS-Addressing . 111Configuring WS-Addressing Attributes . 112Enabling Reliable Messaging .115Introduction to WS-RM . 115WS-RM Interceptors. 116Enabling WS- RM. 118Configuring WS- RM . 121Configuring Artix-Specific WS-RM Attributes . 121Configuring Standard WS-RM Policy Attributes . 122WS-RM Conf iguration Use Cases . 126Configuring WS-RM Persistence. 129Enabling High Availability .131Introduction to High Availability . 131Enabling HA with Static Failover . 132Configuring HA with Static Failover . 134Enabling HA with Dynamic Failover . 135Configuring HA with Dynamic Failover . 137Publishing WSDL Contracts .139Artix WSDL Publishing Serv ice . 139Configuring the WSDL Publishing Serv ice . 140Configuring for Use in a Servlet Container. 143Querying the WSDL Publishing Serv ice . 153AppendixArtix Binding IDs .153iv Artix Deployment Guide: Java
PrefaceWhat is Covered in This BookThis book explains how to configure and deploy Artix for JavaRuntime services and applications, including those written inJAX-WS and JavaScript.Who Should Read This BookThe main audience of this book is Artix systemadministrators. However, anyone involved in designing alarge-scale Artix solution will find this book useful.Knowledge of specific middleware or messaging transports isnot required to understand the general topics discussed inthis book. However, if you are using this book as a guide todeploying runtime systems, you should have a workingknowledge of the middleware transports that you intend touse in your Artix solutions.Organization of this GuideThis guide is divided into the following chapters: Artix Configuration Overview describes Artix Javaconfiguration files. Setting Up Your Environment describes how to set up yourArtix Java environment. Configuring Artix Endpoints describes how to configureArtix Java endpoints. Artix Logging describes how to use logging. Deploying to a Servlet Container describes how to deploy anArtix Java endpoint to a servlet container. Deploying WS-Addressing describes how to configure ArtixJava endpoints to use WS-Addressing. Enabling Reliable Messaging describes how to enable andconfigure Web Services Reliable Messaging (WS-RM). Enabling High Availability describes how to enable andconfigure both static failover and dynamic failover. Publishing WSDL Contracts describes how to enable the ArtixJava WSDL publishing service.Artix Deployment Guide: Java v
The Artix Documentation LibraryFor information on the organization of the Artix library, thedocument conventions used, and where to find additionalresources, see Using the Artix Library: Java.Further Information and Product SupportAdditional technical information or advice is available fromseveral sources.The product support pages contain a considerable amount ofadditional information, such as: The WebSync service, where you can download fixes anddocumentation updates. The Knowledge Base, a large collection of product tips andworkarounds. Examples and Utilities, including demos and additionalproduct documentation.Note:Some information may be available only to customers whohave maintenance agreements.If you obtained this product directly from Micro Focus, contactus as described on the Micro Focus Web site,http://www.microfocus.com. If you obtained the product fromanother source, such as an authorized distributor, contactthem for help first. If they are unable to help, contact us.Information We NeedHowever you contact us, please try to include the informationbelow, if you have it. The more information you can give, thebetter Micro Focus SupportLine can help you. But if you don'tknow all the answers, or you think some are irrelevant toyour problem, please give whatever information you have. The name and version number of all products that youthink might be causing a problem. Your computer make and model. Your operating system version number and details of anynetworking software you are using. The amount of memory in your computer. The relevant page reference or section in thedocumentation.vi Artix Deployment Guide: Java
Your serial number. To find out these numbers, look in thesubject line and body of your Electronic Product DeliveryNotice email that you received from Micro Focus.Contact informationOur Web site gives up-to-date details of contact numbers andaddresses.Additional technical information or advice is available fromseveral sources.The product support pages contain considerable additionalinformation, including the WebSync service, where you candownload fixes and documentation updates. To connect, enterhttp://www.microfocus.com in your browser to go to the MicroFocus home page.If you are a Micro Focus SupportLine customer, please seeyour SupportLine Handbook for contact information. You candownload it from our Web site or order it in printed form fromyour sales representative. Support from Micro Focus may beavailable only to customers who have maintenanceagreements.You may want to check these URLs in particular: x (trial software download and Micro Focus Community files)(documentation updates and PDFs)To subscribe to Micro Focus electronic newsletters, use theonline form /infocus/newsletter-subscription.aspArtix Deployment Guide: Java vii
Artix for JavaConfigurationOverviewArtix takes a minimalist approach to requiring configuration.However, it provides a large number of options for providingconfiguration data.Artix adopts an approach of zero configuration, orconfiguration by exception. Configuration is required only ifyou want to either customize the runtime to exhibit nondefault behavior or if you want to activate some of the moreadvanced features.Artix for Java supports a number of configuration methods ifyou want to change the default behavior, enable specificfunctionality or fine-tune a component’s behavior. Thesupported configuration methods include: Spring XML configuration WS-Policy statements WSDL extensionsSpring XML configuration is, however, the most versatile way toconfigure Artix and is the recommended approach to use.Artix Configuration FilesArtix for Java leverages the Spring framework to injectconfiguration information into the runtime when it starts up. TheXML configuration file used to configure applications is a SpringXML file that contains some Artix specific elements.Spring frameworkSpring is a layered Java/J2EE application framework. Artixleverages the Spring core and uses the principles of Inversion ofControl and Dependency Injection.For more information on the Spring framework, see http://www.springframework.org. Of particular relevance is Chapter 3of the Spring reference guide, The IoC container.For more information on inversion of control and dependencyinjection, see tix Deployment Guide: Java 1
Configuration namespaceThe core Artix configuration elements are defined in thehttp://cxf.apache.org/jaxws namespace. You must add theentry shown in Example 1 to the beans element of yourconfiguration file.Example1. Namespace beans .xmlns:jaxws "http://cxf.apache.org/jaxws. Advanced features, like WS-Addressing and WS-RM, require theuse of elements in other namespaces. The SOAP and JMStransports also use elements defined in different namespaces.You must add those namespaces when configuring thosefeatures.Schema locationSpring XML files use the beans element's xsi:schemaLocationattribute to locate the schemas required to validate theelements used in the document. The xsi:schemaLocation attributeis a list of namespaces, and the schema in which the namespaceis defined. Each namespace/schema combination is defined asa space delimited pair.You should add the Artix configuration schemas to the list ofschemas in the attribute as shown in Example 2.Example 2. Adding the JAX-WS Schema to theConfiguration File beans .xsi:schemaLocation e.org/schemas/jaxws.xsd." Sample configuration fileExample 3 shows a simplified example of an Artix configurationfile.2 Artix Deployment Guide: Java
Example3. Artix Configura tion File beans xmlns "http://www.springframework.org/schema/beans" ❶xmlns:xsi axws "http://cxf.apache.org/jaxws" ❷.xsi:schemaLocation -2.0.xsdhttp://cxf.apache.org/jaxws ❸http://cxf.apache.org/schemas/jaxws.xsd" !-- your configuration goes here! -- ❹ /beans The following describes Example 3:❶An Artix configuration file is actually a Spring XML file. Youmust include an opening Spring beans element that declaresthe namespaces and schema files for the child elements thatare encapsulated by the beans element.❷Before using the Artix configuration elements, you mustdeclare its namespace in the configuration's root element.❸In order for the runtime and the tooling to ensure that yourconfiguration file is valid, you need to add the proper entriesto the schema location list.❹The contents of the configuration depends on the behavioryou want exhibited by the runtime. You can use: Artix specific elements Plain Spring XML bean elementsMaking Your Configuration File AvailableYou can make the configuration file available to the Artix for Javaruntime in one of the following ways: Name the configuration file cxf.xml and add it your CLASSPATH. Use one of the following command-line flags to point to theconfiguration file:-Dcxf.config.file myCfgResource-Dcxf.config.file.url myCfgURLThis allows you to save the configuration file anywhere onyour system and avoid adding it to your CLASSPATH. It alsomeans you can give your configuration file any name youwant.Artix Deployment Guide: Java 3
This is a useful approach for portable JAX-WS applications.It is also the method used in most of the Artix samples. Forexample, in the WS-Addressing sample, located in theInstallDir/samples/ws-addressing directory, the server startcommand specifies the server.xml configuration file asfollows:java -Dcxf.config.file server.xmldemo.ws addressing.server.ServerNOTE: In this example, the start command is run from the directoryin which the server.xml file resides. Programmatically, by creating a bus and passing theconfiguration file location as either a URL or string. Forexample:(new SpringBusFactory()).createBus(URL myCfgURL)(new SpringBusFactory()).createBus(String myCfgResource)4 Artix Deployment Guide: Java
Setting Up YourEnvironmentThis chapter explains how to set-up your Artix Java runtimesystem environment.Using the Artix Environment ScriptTo use the Artix runtime environment, the host computer musthave several environment variables set. Set these variables usingthe artix java env script.Running the artix java env scriptThe Artix installation process creates a script namedartix java env, which captures the information required toset your host’s environment variables. Running this scriptconfigures your system to use the Artix Java runtime. Thescript is located in the InstallDir/bin folder.Artix for Java Environment VariablesThis section describes the following environment variables inmore detail: ARTIX JAVA HOME CXF HOME JAVA HOME ANT HOME PATH CAMEL HOMENOTE: You do not have to manually set your environment variables.You can configure them during installation, or you can set them later byrunning the provided artix java env script.Artix Deployment Guide: Java 5
Environment variablesThe environment variables are explained in Table 1.Table1. Artix Environme nt VariablesVariableARTIX JAVA HOMECXF HOMEDescriptionSpecifies the top level of your Artix installation. Forexample, on Windows, if you install Artix into theC:\Artix directory, ARTIX JAVA HOME should be setto C:\Artix.Specifies the top level of your Artix installation. Forexample, on Windows, if you install Artix into theC:\Artix directory, CXF HOME should be set toC:\Artix.JAVA HOMESpecifies the directory path to your system JDK.ANT HOMESpecifies the directory path to the ant utility. Thedefault location is InstallDir\tools\ant.CAMEL HOMEPATHSpecifies the directory path of the Apache Camellibraries. The default location isInstallDir\lib\camel.The Artix bin directories are prepended on the PATHto ensure that the proper libraries, configurationfiles, and utility programs are used.Customizing your Environment ScriptThe artix java env script sets the Artix environment variablesusing values obtained from the installer. The script checks eachone of these settings in sequence, and updates them, whereappropriate.The artix java env script is designed to suit most needs.However, if you want to customize it for your own purposes,note the points described in this section.Before you beginYou can only run the artix java env script once in any consolesession. If you run this script a second time, it exits withoutcompleting. This prevents your environment from becomingbloated with duplicate information (for example, on your PATH andCLASSPATH). In addition, if you introduce any errors whencustomizing the artix java env script, it also exits withoutcompleting.This feature is controlled by the ARTIX JAVA ENV SET variable,which is local to the artix java env script. ARTIX JAVA ENV SETis set to true the first time you run the script in a console; thiscauses the script to exit when run again.6 Artix Deployment Guide: Java
Environment variablesJAVA HOME defaults to the value obtained from the installer. If youdo not manually set this variable before runningartix java env, it takes its value from the installer.Artix Deployment Guide: Java 7
Configuring ArtixEndpointsArtix endpoints are configured using one of three Springconfiguration elements. The correct element depends on whattype of endpoint you are configuring and which features youwish to use. For consumers you use the jaxws:client element.For service providers you can use either the jaxws:endpointelement or the jaxws:server element.The information used to define an endpoint is typically defined inthe endpoint's contract. You can use the configuration element'sto override the information in the contract. You can also use theconfiguration elements to provide information that is notprovided in the contract.NOTE: When dealing with endpoints developed using a Java-firstapproach it is likely that the SEI serving as the endpoint's contract islacking information about the type of binding and transport to use.You must use the configuration elements to activate advancedfeatures such as WS-RM. This is done by providing childelements to the endpoint's configuration element.Configuring Service ProvidersArtix has two elements that can be used to configure a serviceprovider: jaxws:endpoint jaxws:serverThe differences between the two elements are largely internal tothe runtime. The jaxws:endpoint element injects properties intothe org.apache.cxf.jaxws.EndpointImpl object created to support aservice endpoint. The jaxws:server element injects propertiesinto the nobject created to support the endpoint. The EndpointImpl objectpasses the configuration data to the JaxWsServerFactoryBeanobject. The JaxWsServerFactoryBean object is used to create theactual service object. Because either configuration element willconfigure a service endpoint, you can choose based on thesyntax you prefer.Using the jaxws:endpoint ElementThe jaxws:endpoint element is the default element for configuringJAX-WS service providers. Its attributes and children specify allof the information needed to instantiate a service provider.Artix Deployment Guide: Java 9
Many of the attributes map to information in the service'scontract. The children are used to configure interceptors andother advanced features.Identifying the endpoint being configuredFor the runtime to apply the configuration to the proper serviceprovider, it must be able to identify it. The basic means foridentifying a service provider is to specify the class thatimplements the endpoint. This is done using the jaxws:endpointelement's implementor attribute.For instances where different endpoint's share a commonimplementation, it is possible to provide different configurationfor each endpoint. There are two approaches for distinguishing aspecific endpoint in configuration: a combination of the serviceName attribute and theendpointName attributeThe serviceName attribute specifies the wsdl:service elementdefining the service's endpoint. The endpointName attributespecifies the specific wsdl:port element defining the service'sendpoint. Both attributes are specified as QNames usingthe format ns: name. ns is the namespace of the element andname is the value of the element's name attribute.TIP: If the wsdl:service element only has one wsdl:portelement, the endpointName attribute can be omitted. the name attributeThe name attribute specifies the QName of the specificwsdl:port element defining the service's endpoint. TheQName is provided in the format { ns} localPart. ns is thenamespace of the wsdl:port element and localPart is thevalue of the wsdl:port element's name attribute.AttributesThe attributes of the jaxws:endpoint element configure the basicproperties of the endpoint. These properties include the addressof the endpoint, the class that implements the endpoint, andthe bus that hosts the endpoint.10 Artix Deployment Guide: Java
Table 2 describes the attribute of the jaxws:endpoint element.Table 2. Attributes for Configuring a JAX-WS ServiceProvider Using the jaxws:endpoint ElementAttributeDescriptionidSpecifies a unique identifier that other configurationelements can use to refer to the ationendpointNameSpecifies the class implementing the service. Youcan specify the implementation class using eitherthe class name or an ID reference to a Spring beanconfiguring the implementation class. This classmust be on the classpath.Specifies the class implementing the service. Thisattribute is useful when the value provided to theimplementor attribute is a reference to a bean that iswrapped using Spring AOP.Specifies the address of an HTTP endpoint. This valueoverrides the value specified in the services contract.Specifies the location of the endpoint's WSDLcontract. The WSDL contract's location is relative tothe folder from which the service is deployed.Specifies the value of the service's wsdl:port element'sname attribute. It is specified as a QName using theformat ns: name where ns is the namespace of thewsdl:port element.serviceNamepublishbusbindingUriSpecifies the value of the service's wsdl:serviceelement's name attribute. It is specified as a QNameusing the format ns: name where ns is the namespace ofthe wsdl:service element.Specifies if the service should be automaticallypublished. If this is set to false, the developer mustexplicitly publish the endpoint as described inPublishing a Service in Developing ArtixApplications with JAX-WS and JAX-RSSpecifies the ID of the Spring bean configuring thebus used to manage the service endpoint. This isuseful when configuring several endpoints to use acommon set of features.Specifies the ID of the message binding the serviceuses. A list of valid binding IDs is provided in ArtixBinding IDs.Artix Deployment Guide: Java 11
AttributeDescriptionSpecifies the stringified QName of the service'swsdl:port element. It is specified as a QName usingthe format {ns}localPart. ns is the namespace ofthe wsdl:port element and localPart is the value ofthe wsdl:port element's name attribute.nameSpecifies if the bean is an abstract bean. Abstractbeans act as parents for concrete bean definitionsand are not instantiated. The default is false.Setting this to true instructs the bean factory not toinstantiate the bean.abstractSpecifies a list of beans that the endpoint depends onbeing instantiated before it can be instantiated.depends-oncreatedFromAPISpecifies that the user created that bean using ArtixAPIs, such as Endpoint.publish() or Service.getPort() .The default is false .Setting this to true does the following:1. Changes the internal name of the bean byappending .jaxws-endpoint to its id2. Makes the bean abstractIn addition to the attributes listed in Table 2, you might need touse multiple xmlns:shortName attributes to declare the namespacesused by the endpointName and serviceName attributes.ExampleExample 4 shows the configuration for a JAX-WS endpoint thatspecifies the address where the endpoint is published. Theexample assumes that you want to use the defaults for all othervalues or that the implementation has specified values in theannotations.Example4. Simple JAX-WS Endpoint Configura tion beans. xmlns:jaxws "http://cxf.apache.org/jaxws".schemaLocation ".http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd." jaxws:endpoint id "example"implementor "org.apache.cxf.example.DemoImpl"address "http://localhost:8080/demo" / /beans 12 Artix Deployment Guide: Java
Example 5 shows the configuration for a JAX-WS endpoint whosecontract contains two service definitions. In this case, you mustspecify which service definition to instantiate using theserviceName attribute.ExampleName5.JAX-WS Endpoint Configuration with a Service beans . xmlns:jaxws "http://cxf.apache.org/jaxws".schemaLocation ".http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd." jaxws:endpoint id "example2"implementor "org.apache.cxf.example.DemoImpl"serviceName "samp:demoService2"xmlns:samp "http://org.apache.cxf/wsdl/example" / /beans The xmlns:samp attribute specifies the namespace in which theWSDL service element is defined.Using the jaxws:server ElementThe jaxws:server element is an element for configuring JAX-WSservice providers. It injects the configuration information intothe n . This isan Artix specific object. If you are using a pure Spring approachto building your services, you will not be forced to use Artixspecific APIs to interact with the service.The attributes and children of the jaxws:server element specifyall of the information needed to instantiate a service provider.The attributes specify the information that is required toinstantiate an endpoint. The children are used to configureinterceptors and other advanced features.Identifying the endpoint being configuredIn order for the runtime to apply the configuration to the properservice provider, it must be able to identify it. The basic means foridentifying a service provider is to specify the class thatimplements the endpoint. This is done using the jaxws:serverelement's serviceBean attribute.For instances where different endpoint's share a commonimplementation, it is possible to provide different configurationfor each endpoint. There are two approaches for distinguishing aspecific endpoint in configuration: a combination of the serviceName attribute and theendpointName attributeThe serviceName attribute specifies the wsdl:service elementdefining the service's endpoint. The endpointName attributespecifies the specific wsdl:port element defining the service'sArtix Deployment Guide: Java 13
endpoint. Both attributes are specified as QNames usingthe format ns: name. ns is the namespace of the element andname is the value of the element's name attribute.TIP: If the wsdl:service element only has one wsdl:port element,the endpointName attribute can be omitted. the name attributeThe name attribute specifies the QName of the specificwsdl:port element defining the service's endpoint. TheQName is provided in the format { ns} localPart. ns is thenamespace of the wsdl:port element and localPart is thevalue of the wsdl:port element's name attribute.AttributesThe attributes of the jaxws:server element configure the basicproperties of the endpoint. These properties include theaddress of the endpoint, the class that implements theendpoint, and the bus that hosts the endpoint.Table 3 describes the attribute of the jaxws:server element.Table 3. Attributes for Configuring a JAX-WS ServiceProvider Using the jaxws:server ElementAttributeDescriptionSpecifies a unique identifier that other configurationelements can use to refer to the endpoint.idserviceBeanserviceClassSpecifies the class implementing the service. You canspecify the implementation class using either theclass name or an ID reference to a Spring beanconfiguring the implementation class. This class mustbe on the classpath.Specifies the class implementing the service. Thisattribute is useful when the value provided to theimplementor attribute is a reference to a bean that iswrapped using Spring AOP.Specifies the address of an HTTP endpoint. Thisvalue will override the value specified in the servicesc
Artix Configuration Overview describes Artix Java configuration files. Setting Up Your Environment describes how to set up your Artix Java environment.
