59 Deploying Oracle Service Bus Services

This chapter provides instructions for deploying Service Bus projects and applications to an Oracle WebLogic Server. You can deploy Service Bus components from the Oracle Service Bus Console, JDeveloper, Fusion Middleware Control, and the Service Bus Deployment API. When you deploy to and from different environments, you can use customization files to update environment values like endpoint URIs.

This chapter includes the following sections:

• Deployment Overview

• Before You Deploy

• Deploying from the Oracle Service Bus Console

• Deploying from JDeveloper

• Deploying a Service Bus Configuration JAR File in Fusion Middleware Control

• Updating an Online Configuration

• Updating an Online Configuration in a Cluster

59.1 Deployment Overview

Deployment is the process of packaging Service Bus resources and transferring them to a target application server.

You can deploy resources in multiple ways, including the following:

• Activate the current session in the Oracle Service Bus Console.

• Deploy a project or application using the Deploy command in JDeveloper.

• Export a configuration JAR file to an application server in JDeveloper. You can also deploy to the integrated application server included with JDeveloper to run, debug, and test applications and projects.

• Import a configuration JAR file using Fusion Middleware Control.

• Use the Maven plug-in to deploy Service Bus services in a Maven environment. For more information, see Using the Oracle Service Bus Development Maven Plug-In.

• Use WLST commands to activate sessions and to import configurations and environment values. For more information, see Using the Oracle Service Bus Deployment APIs in Administering Oracle Service Bus.

Once you deploy Service Bus resources, you can monitor and manage them in the runtime using Fusion Middleware Control. For information, see Oracle Service Bus Runtime Management in Administering Oracle Service Bus.

59.2 Before You Deploy

Regardless of which method you use to deploy Service Bus configurations, review this information before deploying.

• Creating a Service Bus Domain Using the Configuration Wizard

• Resolving Conflicts

• Configuring JMS Resources

• Configuring Security

59.2.1 Creating a Service Bus Domain Using the Configuration Wizard

Before you can deploy a Service Bus configuration, you need to have a running Service Bus domain, to which Service Bus resources will be deployed. The domain must have the required schemas in a running database. For information on creating a Service Bus domain with the Oracle Fusion Middleware Configuration Wizard, see Configuring the Oracle Service Bus Domain in Installing and Configuring Oracle Service Bus.

59.2.2 Resolving Conflicts

If there are any conflicts in the Service Bus resources being deployed, the deployment will fail. Before activating resources or exporting them, view and resolve any existing conflicts as described inViewing and Resolving Conflicts. Deploying from JDeveloper or activating from the console will fail if there are any conflicts in Service Bus resources.

59.2.3 Configuring JMS Resources

In addition to configuring JMS file stores in the Oracle Fusion Middleware Configuration Wizard, proxy services and business services that use JMS require the following resources:

• JMS connection factories: You must configure XA or non-XA JMS connection factories for all business services and proxy services implemented using JMS.

• JMS queues/topics: Service Bus automatically configures JMS queues for proxy services that are implemented using JMS if they queues are on the same local Service Bus domain. You must configure JMS queues/topics for all business services using JMS, for proxy services that consume messages from a remote queue, and for proxy services that are implemented using non-JMS.

To concentrate all Service Bus JMS resources in a single JMS module, use the WebLogic Server Administration Console to create a new JMS module containing the destination to be used for the proxy services' endpoint. For more information about configuring JMS resources, see "Methods for Configuring JMS Resources" in Administering JMS Resources for Oracle WebLogic Server.

59.2.4 Configuring Security

Service Bus leverages the security features of WebLogic Server to ensure message confidentiality and integrity (message-level security), secure connections between clients and WebLogic Server (transport-level security), and authentication and authorization (access control). For information on how to configure security for Oracle Service Bus, see Security

Note:

You must configure security separately for each Service Bus domain. Service Bus does not export or import security configurations.

59.3 Deploying from the Oracle Service Bus Console

In the Oracle Service Bus Console, you deploy the services you create by activating your changes to the runtime. Any changes you activate become immediately available in the runtime environment.

You can also update components that are activated in the runtime using the Oracle Service Bus Console.

59.3.1 How to Deploy from the Console

Once you have configured your Service Bus domain, secured it, and added any JMS resources required for its services, you are ready to import the JAR file that contains your Service Bus configuration. After you import the configuration metadata, you can update environment-specific information for your domain. All changes to Service Bus configurations require a session, with the exception of security-related changes.

To deploy the contents of configuration JAR file:

1. Create a session in Service Bus.

   See How to Create a Session.

2. Import all or selected objects from a configuration JAR file.

   See How to Import Resources from a Configuration JAR File in the Console.

3. Update environment-specific information such as service endpoint URIs and directory names.

   See "Finding and Replacing Environment Values Using the Oracle Service Bus Console" or "Using Configuration Files to Update Environment Values and Operational Settings" in Administering Oracle Service Bus.

4. Verify there are no conflicts (indicated by a Conflict icon in the toolbar).

   If there are conflicts, resolve them as described in Viewing and Resolving Conflicts.

5. Activate the session.

   See How to Activate a Session.

You can also import and update a configuration programmatically using the WebLogic Scripting Tool (WLST) and the Service Bus deploymentMBean. For more information, see "Using the Oracle Service Bus Deployment APIs" in Administering Oracle Service Bus.

59.4 Deploying from JDeveloper

The first time you deploy an application or project to the WebLogic Server, the entire application and all projects are published.

On subsequent deployments of the application, only the resources that were changed are published to the server. If there are any conflicts in the any Service Bus resources in the application, the deployment will fail.

59.4.1 How to Create a Connection to the WebLogic Server

In JDeveloper, you must create a connection to the application servers to which Service Bus applications will be deployed. You only need to perform this task once for each application server hosting Service Bus services. You can connect to the following types of servers:

• Standalone Server: A server that is not managed by JDeveloper. Standalone servers include the domains you create using the configuration wizard and WebLogic servers in the Oracle Cloud. Only the Deploy command can be used to deploy to a standalone server, and the server must already be running in order to deploy to it.

• Integrated Server: A server that can be managed by JDeveloper, and only used in development and testing. If you opt to allow JDeveloper to manage the lifecycle of the server when you set up the connection, you can deploy to the server directly from JDeveloper using the Run command or the Deploy command. If JDeveloper does not manage the lifecycle, you need to start and stop the server manually. In that case, the Run command can only be used for deployment if the server is already running.

To create an application server connection:

1. If the Application Servers navigator is not visible, click the Window main menu, and select Application Servers.
2. In the Application Servers navigator, right-click Application Servers and select New Application Server.

   The Create Application Server Connection wizard appears.

3. Select either Standalone Server or Integrated Server.
4. Click Next.
5. Do one of the following:

   • If you selected Standalone Server: Enter a name for the connection. If you are connecting to an Oracle Cloud server, select Oracle Cloud from the Connection Type list. Otherwise, leave the connection type at its default value (WebLogic 12.x).

   • If you selected Integrated Server: Enter the connection name. If you want to be able to start the server in Run and Debug mode from JDeveloper, select Let JDeveloper manage the lifecycle for this Server Instance, and enter the location of the domain and server instance.

6. Click Next.
7. On the Authentication page, enter the user name and password to connect to the WebLogic server, and then click Next.
8. On the Configuration page, enter the following information:

   Option	Description
   If creating an Oracle Cloud server connection:	Data Center: The data center to use, or if necessary, enter the short code for a new data center. For example, in US Commercial 1 [us1] the short code is us1. Identity Domain: Enter the identity domain for Oracle Cloud Service instance. Service Name: Enter the service name for your Oracle Cloud Service instance. After you sign up for Oracle Cloud service, you will receive information about the data center, the identity domain, and the service name which you enter here to establish a connection to your Oracle Cloud service instance.
   If creating a non-cloud server connection:	WebLogic Hostname (Administration Server): The name of the server on which the WebLogic server resides. WebLogic Hostname (Administration Server): The name of the server on which the WebLogic server resides. SSL Port: The SSL port number used by the WebLogic server. To use secure socket layer (SSL), select the Always use SSL check box. WebLogic Domain: The name of the WebLogic server domain. For additional information about specifying domains, click Help.

9. Click Next.
10. On the Test page, click Test Connection to verify the server connection.

    Note:

    The test is only successful when performed against a running server.

11. If the connection is successful, click Finish. Otherwise, click Back to make corrections in the previous dialogs.

    Even if the connection test is unsuccessful, a connection is created.

59.4.2 How to Create a Deployment Profile

A deployment profile provides JDeveloper with information about the application server to which a project or application will be deployed. The type of profile indicates whether to deploy only the selected project or the entire Service Bus application. Service Bus attaches a default project deployment profile to each Service Bus project you create, and a default application deployment profile to each Service Bus application. You can define additional deployment profiles, each of which deploy to a different application server.

For additional information about working with deployment profiles, see "How to Create and Edit Deployment Profiles" in Developing Applications with Oracle JDeveloper.

To create a deployment profile:

1. In the Application Navigator, right-click the Service Bus project.
2. Point to Deploy, and select New Deployment Profile.

   The Create Deployment Profile dialog appears.

3. In the Profile Type field, do one of the following:

   • To define a profile that deploys just the selected project, select Service Bus Project.

   • To define a profile that deploys all projects in the application that contains the selected project, select Service Bus Configuration.

4. In the Deployment Profile Name field, enter a unique and identifying name for the profile.
5. Click OK.
6. Click Save.

59.4.3 How to Customize Your Service Bus Deployment

You can customize Service Bus deployment in JDeveloper.

To customize your Service Bus deployment in JDeveloper:

1. From the Application menu, select Application Properties.
2. Click Service Bus Configuration.
3. Do one of the following:
   1. Select Use Custom Settings, and then click the Customize Settings button, to customize deployment settings that can be used for multiple Service Bus applications in JDeveloper.
   2. Select Use Application Settings to customize the deployment settings for the currently-selected Service Bus application in JDeveloper.
4. Edit the following settings to match your deployment preferences:

   Element	Description
   Preserve Settings	Contains options for preserving settings.
   Preserve Environment Variable Values	Select this option when you want to preserve the environment variables values in the existing resources on the importing system.
   Preserve Security and Policy Settings	Select this option to preserve the importing system's security configuration (excluding access control policies) and the references to the WS-Policies bound directly to the service (instead of bound to the WSDL document). When you select this option, the values in the existing resources are preserved when you import them, even if the security and policy configurations have been updated in JDeveloper.
   Preserve Credentials (Username/Password)	Select this option to preserve the importing system's PKI credentials in service key providers, user name and passwords in service accounts, and user name and password credentials in SMTP servers, JNDI providers, and UDDI registries.
   Session Settings	Contains options for Service Bus session settings when publishing artifacts to a Service Bus deployment.
   Discard Session if Activation Fails	Select this option if you elected to activate the session once the import is complete and you want to discard the session if the session activation fails. Failure might occur if importing any of the resources results in a conflict.
   Description	Enter a brief description for the session.
   Deployment Customization File	Specify a customization file to include in the import or click Browse to navigate to and select a configuration file. For information on customization, see Using Configuration Files to Update Environment Values and Operational Settings in Administering Oracle Service Bus.
   Keystore File	Click Browse to select a keystore file, used to configure the service account and service key provider while working with Service Bus components in JDeveloper. Note: This should be the same keystore the target server points to.
   Password	Enter the password for the Keystore File.

5. Click OK to save your changes.

59.4.4 How to Deploy a Service Bus Project or Application

You can deploy just the selected project to the WebLogic server, or you can deploy the entire application in which the selected project is located. Project-level deployments are not incremental and publish the full project and any of its dependencies. When you deploy a project or application, you select the deployment profile to use for the process. The profile you use determines whether to deploy just the project or the entire application. The default profile generated for each project only deploys the project.

Service Bus and JDeveloper now support deploying directly to Oracle Cloud servers. See How to Create a Connection to the WebLogic Server for more information about creating connections to Oracle Cloud servers.

Note:

You can also publish to the server using the Run command, which deploys to the selected server and launches the Service Bus Test Console. Note that you can only use the Run command for integrated-type servers. For more information, see Accessing the Test Console.

Before You Begin

Make sure you have a connection to the application server, as described in How to Create a Connection to the WebLogic Server. If you do not want to use the default deployment profile, create a new profile, as described in How to Create a Deployment Profile.

To deploy a project or application:

1. In the JDeveloper Application Navigator, right-click the project to deploy.
2. Point to Deploy and select the name of the deployment profile to use.

   Make sure to select the correct profile. To deploy just the project, select a profile with a type of Service Bus Project. To deploy the entire application, select a profile configured with a type of Service Bus Configuration. You can view deployment profile configurations in the project properties.

3. On the Deploy wizard, select Deploy to Service Bus Server, and then click Next.
4. On the Select Server page, select the name of the application server connection for the server to which you are deploying.

   If the server does not exist in the Application Servers list, click Add an Application Server and complete the Create Application Server Connection wizard, as described in How to Create a Connection to the WebLogic Server..

5. To overwrite existing deployed artifacts select Overwrite modules of the same name.
6. Click Next.
7. Review the summary information for the deployment, and then click Finish.

   You can view the progress of the deployment in the Deployment - Log window.

59.4.5 How to Deploy a Project or Application Using the Previous Configuration

After you have deployed a project once, you can skip the Deploy wizard in subsequent deployments if you want to use the same configuration. When you skip the Deploy wizard, Service Bus uses the same deployment profile and same selections you made on the Deploy wizard when you deployed the project the previous time.

To deploy using the previous configuration:

1. In the JDeveloper Application Navigator, right-click the project to deploy.
2. Point to Deploy and select Deploy to Service Bus Server.

   The project is deployed using the last configuration used to deploy the project. You can view the progress of the deployment in the Deployment - Log window.

59.4.6 What Happens When You Deploy Using JDeveloper

If deployment is successful, the deployed project appears in the following locations:

• The Resources window under Application Server > server_connection_name > Service Bus > Service_Bus_server_name.

• The Application Server Navigator under server_connection_name > Service Bus > Service_Bus_server_name.

You are now ready to monitor your application from Oracle Enterprise Manager Fusion Middleware Control. For information, see Introduction to the Management and Monitoring Pages in Administering Oracle Service Bus.

If deployment is unsuccessful, view the messages that appear in the Deployment log window and take corrective actions.

59.5 Deploying a Service Bus Configuration JAR File in Fusion Middleware Control

You can deploy Service Bus configuration JAR files by importing the files into Fusion Middleware Control. Configuration JAR files contain Service Bus resources that were previously exported from a different Service Bus environment.

The export and import features let you easily move projects and resources between environments. When you import a JAR file, you can also import a separate configuration file that updates operational settings and environment values in the imported resources to match the new environment. For example, a configuration file can update host names and port numbers, enable or disable monitoring for a service, and so on.

For information about importing resources into Fusion Middleware Control, see "Importing Oracle Service Bus Resources in Fusion Middleware Control" in Administering Oracle Service Bus. For information about environment configuration files, see "Using Configuration Files to Update Environment Values and Operational Settings" in Administering Oracle Service Bus.

59.6 Updating an Online Configuration

Once a configuration is deployed, Service Bus allows you to change the configuration information for a system dynamically without the need to restart the server for changes to take affect.

You can change a resource, a project, or a number of resources (related or unrelated) using procedure outlined in How to Deploy from the Console. In step 2, you can modify resources directly in the console, or import all or a subset of objects from a configuration JAR file.

The changes are consolidated and sent to all servers (administration and Managed Servers, if you are working in a cluster environment). These changes update the persisted configuration data and also cause other runtime tasks to be performed (such as creating proxy services and JMS queues, compiling XQueries, and so on).

Figure 59-1 illustrates how the system processes messages in the event that the configuration is updated while messages are being processed through the system. Table 59-1 describes the versions for the resources for the sample system illustrated in Figure 59-1.

Table 59-1 Initial and Updated Configuration for a Sample System

Resource	Initial Version	Updated Version
Proxy Service	X	A
MFL	Y	B
XQuery	W	C

Figure 59-1 Sample Online Update Scenario

Description of "Figure 59-1 Sample Online Update Scenario"

Note the following characteristics of the message processing illustrated in the preceding figure:

• Message 1 is already in the system at t1 (the time the configuration is updated)

• Message 1 completes processing by the original (pre-update) resources (X, Y, W)

• Message 2 starts and completes processing with the new configuration (resources A, B, C)

Service Bus tries to execute messages with the version of the proxy service and artifacts available when the messages enters the proxy service. This ensures that a message has a consistent view of the artifacts. If the message processor cannot guarantee this behavior for a message, it will reject the message rather than process it incorrectly.

59.6.1 What You Need to Know for Successful Online Configuration Updates

This section describes guidelines to follow and limitations to be aware of when you update a configuration in a running Service Bus system.

• If you are concerned about message rejection by Service Bus, use the JMS transport protocol with retries. With retries, any messages that are rejected because the system cannot guarantee their processing by compatible resources will be retried.

• Update security-related configuration first, and then update the Service Bus resources in your system. Security configuration changes must be made at the WebLogic Server level before they are visible to Service Bus, especially for activation purposes. For instance, you must configure SSL-related options at the domain level (enable SSL port, configure identity and trust for the domain, etc.) before you can enable a proxy service to use SSL. To learn about updating security resources, see Overview of Security Management in Administering Security for Oracle WebLogic Server.

• Updates must be compatible with existing clients using the system. See Changing an Online Proxy Service.

• If you are updating the configuration to a cluster, it is possible that the updates are done at different times on different Managed Servers. Consequently, messages could be processed by different versions of a proxy service, depending on which Managed Server gets the message to process. This depends on load balancing across Managed Servers.

• During online deployment, Service Bus checks whether the correct versions of referenced resources are used for message processing. If this is temporarily not true, an error is returned. However, if the interface artifact of an invoked service changes (for example, an MFL or WSDL file), the invoking proxy service may not return an error although it temporarily sees a version of the artifact that does not correlate with the proxy service version.

59.6.2 Changing an Online Business Service

Enterprise information services (EIS) are sometimes phased out, and new instances (possibly with new versions of EIS software, new hardware, and so on) are brought online. When this happens, Service Bus administrators need to gracefully transition to the new EIS instance by modifying any affected Service Bus business services.

For information about using the Oracle Service Bus Console to change an endpoint URI for a business service, see How to Configure a Business Service Transport.

59.6.3 Changing an Online Proxy Service

While the majority of the metadata that defines a proxy service can be deployed without change in a new environment, there is some information you may need to update. For example, definitions of proxy services for File, FTP, and email message types must specify a single Managed Server for deployment of polling runtime components in a cluster.

As your business requirements change, you may need to make changes to your proxy services. If the changes you need to make are backward compatible, you can dynamically make changes online using the Oracle Service Bus Console to create a new version of the proxy service. Changes are backward compatible if they meet one of the following criteria:

• The interface of the changed object is unchanged.

• Old and new clients will work with the interface.

If the changes you need to make are not backward compatible, there are two alternatives to consider that would enable you to make the changes online:

• Create and deploy a new proxy service having a different name and URL from that of the earlier version. Clients upgrade by accessing the new proxy service. This enables you to run the old and new versions of a proxy service in parallel, and supports a gradual migration to the new proxy service.

• Force backwards compatibility by changing the proxy service interface to support both the new interface and the old interface (for example, using XML schema choice) and perform different logic in the message flow based on the document received. Clients continue to access the proxy service by using its original URL.

Service Bus cluster domains have additional system administration requirements for deployment of proxy services that are not backward compatible. For more information, see Installing a New Version of a Proxy Service in a Cluster.

59.6.4 Changing an Online Pipeline

Pipelines route messages to named destinations, such as business services, other proxy services, and so on. Message routing definitions may need to be updated in a new environment.

59.7 Updating an Online Configuration in a Cluster

Updating Service Bus components in a cluster requires some additional considerations to those for a non-clustered environment.

For information about performing online updates, see Updating an Online Configuration.

59.7.1 Changing a Business Service in a Cluster

The procedure for changing a business service is the same in both non-clustered and cluster environments. However, the procedure for deploying changes to a business service in a cluster depends on the types of changes made to the business service and the nature of any other changes that might be deployed simultaneously. For more information, see the description of installation strategies in the following section.

For information about changing a business service, see Changing an Online Business Service.

59.7.2 Installing a New Version of a Proxy Service in a Cluster

You can make changes to proxy services dynamically online, partially offline, or completely offline. If your changes are backward compatible (that is, you are making no changes to interfaces), you can make your changes dynamically online using the Oracle Service Bus Console. Making other types of changes should be done partially or completely offline, which requires additional system administration steps.

Making changes that include non-backward compatible changes to proxy service interfaces requires complete offline deployment. To install the new version, follow the procedure below while all servers are operational:

1. Quiesce all inbound messages.
2. Confirm all asynchronous backlogged messages have been processed.
3. Make the necessary changes in the proxy service, and test to verify the proxy service operates as required.
4. Resume accepting inbound messages.

For more information about backward compatibility and installation strategies, see Changing an Online Proxy Service.