The migration strategy depends on the version of EntireX you have been using. This document covers the following topics:
This section covers the following topics:
Update the start script to set the paths to current installation. If the properties file contains a path to the configuration file, you may need to adjust the path. The properties and configuration files can be used as before. See Configuration File for the XML/SOAP RPC Server under UNIX | Windows for more information.
Update the start script to set the paths to current installation.
Save your Web services (AAR files) and modified configuration files (i.e. axis2.xml). You do not need to re-generate your Web services (AAR files). If the configuration was modified, perform the same modifications for the new installation and restart Software AG Web Server. Redeploy the web services (AAR files).
Note:
The new installation will use another port by default, which means that the Web clients need to be adjusted.
Save your Web services (AAR files) and modified configuration files (i.e. axis2.xml). You do not need to re-generate your Web services (AAR files). For deployment of file wsstack.war and copying file entirex.jar to Web Services Stack, see the separate Web Services Stack documentation in the Software AG Infrastructure Administrator's Guide, also available under http://documentation.softwareag.com > Guides for Tools Shared by Software AG Products.
If configuration was modified, perform the same modifications for new installation and restart the Web server. Redeploy the Web services (AAR files).
The architecture of the EntireX XML/SOAP Listener (formerly known as XML Servlet) and EntireX XML/SOAP RPC Server was changed with version 8.0. The previous version worked as a Web application running directly in the Web server; the current version works as part of Software AG Common Web Services Stack (WSS), which is a Web application running in a Web server. This change has impact on configuration, packaging and deployment of EntireX Web services.
Note:
This section describes migration from a version earlier than 8.
Migrating from Version 7.n to one or more Listener Services with new URL(s)
Migrating from Version 7.n to one Listener Service, Keeping the URL used by Applications
The XML/SOAP RPC Server requires the directory of a Software AG Common Web Services Stack
installation. The JAR file wsstack-client.jar located in
<WS_STACK_HOME>/lib must be added to
classpath. (Note: the JAR file
wsstack-client.jar must remain in this
lib directory). File entirex.jar from
EntireX installation must also be present in classpath.
The XML parser required has changed. Therefore, the (optional) properties file (if used) must be modified by redefining the parameter for the XML stream parser in the following way:
entirex.sdk.xml.runtime.xmlparserfactory=com.ctc.wstx.stax.WstxInputFactory
The configuration file can be used as before. To make use of the latest features, some extensions in the configuration file are required. See Configuration File for the XML/SOAP RPC Server under UNIX | Windows for more information.
The used XML parser has changed. XML/SOAP Wrapper uses XMLStreamParser, so the classpath must contain the JAR files of XMLStreamParser. The EntireX installation comes with stax-api.jar and wstx-asl.jar. The two XMLStreamParser JAR files are located in <EntireX Home>/classes.
If you are compiling source using the class XMLRPCService, you require an additional JAR file axiom-api-<version>.jar.
This JAR file is located in <WebservicesStack>/lib.
The XML/SOAP Listener requires a Software AG Common Web Services Stack (WSS) installation. The WSS Web application is the container of XML/SOAP Listener. In previous EntireX versions (lower than version 8) the XML/SOAP Listener was referred to as "XML Servlet" and was a Web application itself. The file entirex.jar containing the XML/SOAP Runtime is placed in directory lib of the WSS Web application. An EntireX Web service is created using the XML Mapping Editor as in previous versions, and using a Packaging Wizard to build an AAR file. The AAR file contains all information for this Web service and must be deployed to the Web application.
The following new terms are applicable:
AAR Files
EntireX packs the XMM file(s) and some more files in a Web service
archive (.aar) that is deployed in the Web application WSStack. To put one or
more XMM files in one Web service archive, select the XMM files and from the
context menu choose . All the files you select must have the same mapping
type (i.e. SOAP or non-SOAP mapping); do not mix mapping types.
The servlet entirex-forward only forwards
the message to the new URL. This means you can continue using the old URL and
migrate the service to a new infrastructure. The servlet does not process the
payload, so this Web application does not contain an
entirex.jar file and does not contain a mapping file
(XMM).
The following scenarios are available for migrating a service offered by XML Servlet of earlier EntireX versions (lower than version 8):
migrating to one or more services, using new URL(s); see Migrating from Version 7.n to one or more Listener Services with new URL(s)
migrating to one service only, keeping the URL; see Migrating from Version 7.n to one Listener Service, Keeping the URL used by Applications
You can migrate a service offered by XML Servlet of earlier EntireX versions (lower than version 8) to one or more services in the context of XML/SOAP Listener with new URL(s). That means you can split the original service into different services, each with its own URL. However, this means you need to update the address in the Web client.
To migrate a service with new URLs
Copy all the IDL-XML mapping files (XMMs) listed in file xml-init.xml to one Eclipse project.
Select multiple XMM files that are to be bundled in one service, and from the context menu choose .
Modify the service name if required.
Clear Use of defaults.
Check General service parameters (xml-init.xml) if you have any XMM-independent settings in file xml-init.xml.
Check Set connection and security parameters in mapping file.
Follow the wizard.
Modify the setting if required. The included XMM files can be selected with combo box at the top.
Deploy the service.
Change the target URL of calling instances (Web clients).
The first step is to generate one service archive with all XMM files listed in file xml-init.xml. The second step is the configuration and usage of entirex-forward.war. This section covers the following topics:
To generate a service archive
Copy all IDL-XML mapping files (XMMs) listed in xml-init.xml to one Eclipse project.
Select all XMM files, and from the context menu choose .
Modify the service name if required. This service name is used for
configuring of servlet entirex-forward later.
Clear Use of defaults.
Check General service parameters (xml-init.xml)' if you have any XMM-independent settings in file xml-init.xml.
Check Set connection and security parameters in mapping file.
Follow the wizard.
Modify the setting if required. The included XMM files can be selected with combo box at the top.
Deploy the service.
This Web application delivered as entirex-forward.war allows you to forward a SOAP/XML request from an endpoint used in an older EntireX version (e.g. http://hostname:port/entirex/xmlrt) to an endpoint used in the current EntireX version (e.g http://hostname:port/wsstack/services/example).
The steps below explain how to forward, for example, from the endpoint http://localhost:10010/entirex/xmlrt to the endpoint http://localhost:10010/wsstack/services/example.
Important:
The servlet entirex-forward forwards
the calls to exactly one service and replaces the old EntireX Web application;
it does not run in parallel (old EntireX XML Servlet and the new servlet
entirex-forward).
Note:
You cannot use the file
entireX-forward.war to forward a call from one Web
application server to another.
To forward a SOAP/XML request
Rename entirex-forward.war to entirex.war.
Deploy entirex.war into the webapps folder of your application server (e.g. Tomcat).
Make sure that the Web Services Stack Web application (wsstack.war) is still deployed in the same webapps folder.
Make sure that a service with the name "example" is deployed into the Web Services Stack Web application. See Step 4 under Step 1: Generate Service Archive.
Make sure that your application server allows cross-context
access. Set the crossContext attribute of all
Context implementations to "true". In
Apache Tomcat you can modify the file
$CATALINA_HOME/conf/context.xml:
Set
<Context>
to
<Context crossContext="true">
Make sure that the file web.xml (located in webapps/entirex/WEB-INF) contains the following entries:
<servlet> <description> This is the EntireX ForwardServlet</description> <display-name> forward</display-name> <servlet-name>forward</servlet-name> <servlet-class> com.softwareag.entirex.xml.forward.ForwardServlet</servlet-class> <init-param> <description> This is the targetURI</description> <param-name>targetURI</param-name> <!--replace the servicename with service name defined in aar --> <param-value>/services/servicename</param-value> </init-param> <init-param> <description> This is the target context i.e. /wsstack</description> <param-name>targetContext</param-name> <param-value>/wsstack</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>forward</servlet-name> <url-pattern>/xmlrt</url-pattern> </servlet-mapping>
The old endpoint http://hostname:port/entirex/xmlrt is
built from the name of the Web application
("entirex.war") and the
url-pattern of the servlet
entirex-forward ("/xmlrt").
The new endpoint is built from the
targetContext(/wsstack) and the
targetURI(/"services/servicename").
You can modify these parameters to adapt your Web service.
This section describes how a migrated service interacts with
servlet entireX-forward.
For this example, the Tomcat installation that comes with the EntireX installation (Version 8.2) is used. The assumed endpoint from the previous XML Servlet installation is http://localhost:10010/entirex/xmlrt. The endpoint of the migrated service will be http://localhost:10010/wsstack/services/exampleXML.
The start point is file xml-init.xml (below), with its mapping file example.xmm.
Follow the steps above for generating a Web service archive file (*aar) with service name "exampleXML" (see Step 1: Generate Service Archive). The installation contains the generated exampleXML.aar in directory <installation home>/EntireX/examples/RPC/basic/example/XMLClient. File exampleXML.aar is also deployed during installation if the Software AG Common Platform was selected.
The last step is to configure and deploy the servlet
entirex-forward.
To configure and deploy the servlet
entirex-forward
Rename entirex-forward.war to entirex.war.
Deploy entirex.war to the webapps folder of your application server (e.g. Tomcat).
Make sure that the Web Services Stack Web application (wsstack.war) is still deployed in the same webapps folder.
Make sure that a service with the name "exampleXML" is deployed into the Web Services Stack Web application. If the Web server is running, start a browser session and enter URL http://localhost:10010/wsstack/services. The service "exampleXML" should be listed.
Make sure that your application server allows cross-context
access. See the crossContext attribute of all
Context implementations to "true". In
Apache Tomcat you can modify file
$CATALINA_HOME/conf/context.xml:
Set
<Context>
to
<Context="true">
Make sure that file web.xml (located in webapps/entirex/WEB-INF) contains the following entries:
<servlet> <description> This is the EntireX ForwardServlet</description> <display-name> forward</display-name> <servlet-name>forward</servlet-name> <servlet-class> com.softwareag.entirex.xml.forward.ForwardServlet</servlet-class> <init-param> <description> This is the targetURI</description> <param-name>targetURI</param-name> <param-value>/services/exampleXML</param-value> </init-param> <init-param> <description> This is the target context i.e. /wsstack</description> <param-name>targetContext</param-name> <param-value>/wsstack</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>forward</servlet-name> <url-pattern>/xmlrt</url-pattern> </servlet-mapping>
The old endpoint http://hostname:port/entirex/xmlrt is
built from the name of the Web application
("entirex.war") and the URL pattern of the servlet
entirex-forward ("/xmlrt").
The new endpoint is built from the
targetContext(/wsstack) and the
targetURI(/"services/exampleXML").
Restart Tomcat.
Open the Software AG Designer and change to the EntireX perspective.
Choose to open the XML Tester.
Browse for <installation home>/EntireX/examples/RPC/basic/example/XMLClient/example.xmm.
Create a sample request document.
Start Java RPC server with script
jrpcserver.bat or
jrpcserver.bsh (depending on platform) in directory
bin of the EntireX installation that is used as a
back-end.
Select HTTP Test (XML/SOAP listener).
Set HTTP URI to "http://localhost:10010/wsstack/services/exampleXML".
Send request to see the service works.
Set HTTP URI to "http://localhost:10010/entirex/xmlrt".
Send request again (the request is sent to "old" address and will be processed in the XML/SOAP Listener embedded in Web Services Stack).