1. Developing Services with Oracle Service Bus
  2. Working with Oracle Service Bus Resources
  3. Creating and Configuring Project Resources

6 Creating and Configuring Project Resources

This chapter provides information about project resources you can create to support your Service Bus services, and provides links to additional resources. Project resources can be shared and re-used among services throughout a session. Local resource include things like authentication accounts, JAR files, MQ connections, email or JMS alert destinations, mappings, and so on. Several of these resources can be referenced from proxy and business services, and need to be created before you can configure the proxy or business services that use them.

This chapter includes the following topics:

The following topics provide information and instructions for additional local resource types:

Introduction to Service Bus Project Resources

Service Bus project resources refer to those resources that can be referenced by several components within an application or session. They are also known as local resources.

Project resources include things like service accounts, which define authentication information for remote servers; XML documents and schemas; JAR files; XSLT and XQuery mappings; WSDL and WADL files; and so on. Certain Service Bus components require access to specific project resources, and those project resources must be created before you can create the components that rely on them. For example, if you create a proxy service with an email transport, you must first create the service account that defines the login information for the email server. To create an MQ proxy or business service, you must first create the MQ connection resource.

Project Resources and Sessions in the Oracle Service Bus Console

When you create, modify, or delete project resources in the Oracle Service Bus Console, you must be in an active session. If you discard the session, any project resources your created and the associated data are also discarded. When you activate a session after creating or modifying resources, Service Bus makes that information available to the runtime.

Working with Service Accounts

A service account provides a user name and password that proxy services and business services use for outbound authentication or authentication to a local or remote resource, such as an FTP server or a JMS server. The user names and passwords that you define for Service Bus access are used for inbound authentication and for authenticating administrative requests.

For example, if a business service is required to supply a user name and password for transport-level authentication with a web service, you create a service account that specifies the user name and password. You then configure the business service to include the service account credentials in its outbound requests.

Service Account Authentication Types

You can use the same service account for multiple business services and proxy services. To specify the user name and password that a service account provides, you can define any of the following types:

Static

With a static type of authentication, you save a user name and password with the service account configuration. The service account encodes this user name and password in the outbound request. Use this type of authentication when the login information does not need to change for different messages.

User Name and Password Pass-Through

A pass-through service account provides the user names and passwords that it receives from incoming client requests. For example, if an inbound HTTP basic request contains pat and patspassword as the user name and password, the service account encodes pat and patspassword in the outbound request.

Because this type requires that client requests include clear-text user names and passwords, it is applicable only for client requests that use either the HTTP basic protocol, a Web Services Security Username Token authentication with a clear-text password, or a custom user name and password token.

Oracle recommends that you use this technique only when Service Bus and the endpoint belong to the same authentication domain. For example, use this technique when you are routing messages within a single organization and both Service Bus and the message consumer authenticate against a common LDAP server.

The following restrictions apply to this technique:

  • It cannot be used in outbound requests that authenticate Service Bus to a local or remote server or system resource, such as an FTP server or a JMS server.

  • It cannot be used with the fn-bea:lookupBasicCredentials XQuery function. For more information, see Service Bus XQuery Functions.

    Note:

    If your proxy is an active WSS intermediary, you can use WS-Security to encrypt a WS-Security Username Token or custom user name and password. In this instance, user name and password pass-through works because the proxy first decrypts the request and then has access to the clear-text user name and password.

User Mapping Authentication

A service account that uses mapping authentication maps the user name from one or more authenticated clients to user names and passwords that you specify. The mapping authentication type requires you to correlate (map) the user name obtained by authenticating an inbound request from a client (the local user name) to a user name and password that you specify (the remote user name and password). When the service account receives a request from an authenticated client that has been mapped, it provides the appropriate remote user name and password for the business service or proxy service outbound request.

If the client authenticates at both the transport level and message level, the service account maps the message level user name to the remote user name and password. You can also map an anonymous user name to a remote user name and password.

The following restrictions apply to mapping authentication:

  • It cannot be used in outbound requests that authenticate Service Bus to a local or remote server or system resource, such as an FTP server or a JMS server.

  • It cannot be used with the fn-bea:lookupBasicCredentials XQuery function. For more information, see Service Bus XQuery Functions.

How to Create Service Accounts

Use service accounts to provide authentication information to proxy and business services for outbound authentication or for resource authentication, such as FTP and JMS servers. Service accounts can define authentication information in the following ways:

  • Providing a static user name and password.

  • Passing the incoming user name and password through to the server.

  • Mapping the incoming user name and password to a user name and password you specify.

For more information about these authentication types, see Service Account Authentication Types. For more information about service account properties, see the online help provided with Service Bus.

Creating a Service Account with a Static Password

To create a service account with a static password:

  1. Create a service account, as described above.
  2. On the Service Account Definition Editor, select Static for the type.

    Tip:

    If you are working in the Oracle Service Bus Console, you can also select Static for the type on the Create Service Account dialog when you first create the resource.

    User name and password fields appear in the editor.

  3. Enter the user name and password, and then confirm the password you entered. To encrypt these credentials, see the steps below.
  4. In the toolbar, click Save.
How to Enable Encryption of Service Account Credentials

By default, the user name and password for a service account are not encrypted. If you want to encrypt these credentials, you must manually enable encryption in JDeveloper before you create the service account:

  1. From the Tools menu, select Preferences.

  2. Select ServiceBus Service Account.

  3. Select Enable encryption on service account user credentials.

Note:

The encryption of service account credentials is machine-specific. This means that in a development environment where multiple developers on different machines work on the same project using source control, they will not have access to the service account as one machine cannot decrypt credentials encrypted on another machine. To share projects that include encrypted service account credentials across machines, you can use JDeveloper to export and import Service Bus projects. During export, JDeveloper decrypts the service account credentials, allowing the project to be successfully imported using JDeveloper on a different machine. See Importing and Exporting Resources in JDeveloper.
Creating a Service Account that Passes Though Authentication Information

To create a service account that passes through authentication information:

  1. Do one of the following:

    • For JDeveloper: In the Application Navigator, right-click the project or folder to contain the new service account, point to New, and select Service Account.

    • For Oracle Service Bus Console: In the Project Navigator, right-click the project or folder to contain the new service account, point to Create, and select Resource. Click Security, click Service Account, and then click OK.

  2. Enter a unique name for this service account, and an optional description.
  3. Click Create or Finish.

    The Service Account Definition Editor appears. By default, the type is Pass Through.

  4. Click Save.

    The service account is created and saved in the current session.

Creating a Service Account that Maps Incoming Passwords

To create a service account that maps incoming passwords:

  1. Create a service account, as described above.

  2. On the Service Account Definition Editor, select Mapping for the type.

    Tip:

    If you are working in the Oracle Service Bus Console, you can also select Mapping for the type on the Create Service Account dialog when you first create the resource.

    Mapping tables appear in the editor.

  3. In the Remote Users table, do the following:

    1. Click the Add icon above the table.

    2. In the new row that appears, enter the user name and password that you want to send in outbound requests.

    3. Repeat the above steps for each remote user to add.

    4. To remove a remote user, select the row in the table and click the Delete icon.

  4. To map remote users to local users, do the following in the Local Users table:

    1. Click the Add icon above the table.

    2. In the Local User Name column, enter the name that identifies a client that has been authenticated on its inbound request.

    3. From the Remote User Name list of options, select the user name to send in outbound requests for the authenticated user you specified in the Local User Name field.

      The list of options is populated from the values you created in the Remote Users table.

    4. Repeat the above steps for each local user to add.

      Note:

      If you have not already added these users in Fusion Middleware Control, do so before you use this mapping in a runtime environment. Otherwise, the mapping will never match an authenticated user and will never be used. For more information about adding users, see "Creating Oracle Service Bus Users" in Administering Oracle Service Bus.

    5. To remove a local user, select the row in the table and click the Delete icon.

  5. To map anonymous requests to a specific remote user account, select Map Anonymous Requests to Remote User, and then select the user name from the list of options.

    This list of options is also populated from the values you created in the Remote Users table.

  6. In the toolbar, click Save.

How to Edit Service Accounts

Once you create a service account you can modify its description and authentication type, including updating static login credentials, and adding and removing remote and local users for mapped authentication.

To edit a service account:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the service account to edit.
  2. Right-click the service account name, and select Open.
  3. Make any of the following changes:

    • Update the description.

    • Change the authentication type. Make sure to reconfigure the authentication information, as described in How to Create Service Accounts.

    • For mapped authentication types: Add or remove remote and local users, modify remote user passwords, modify local user mappings, and update anonymous user mappings.

      For more information about these tasks, see Creating a Service Account that Maps Incoming Passwords and the online help.

    You cannot change the service account name.

  4. When you are done making changes, click Save.
  5. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

    Note:

    If the service account that you modified authenticates with a WebLogic JMS server, the JMS server might not recognize your modification for up to 60 seconds. By default, WebLogic Server JMS checks permissions for each destination every 60 seconds. To change this behavior, modify the WebLogic Server startup command by setting the following system property to the frequency (in seconds) that you want WebLogic Server JMS to check permissions: weblogic.jms.securityCheckInterval.

    A value of 0 (zero) for this property ensures that a permissions check is performed for every send, receive, and getEnumeration action on a JMS resource.

How to Delete Service Accounts

When you delete a service account, the user name, password, or local-user to remote-user mapping data that the service account defines are also deleted. You can delete the service account even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

Before you Begin:

If any business service or proxy service is configured to use the service account, remove the service account from the business service or proxy service. In the Oracle Service Bus Console, open the service account in the Service Account Definition Editor and click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the service account and select Explore Dependencies.

To delete a service account:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the service account to delete.
  2. Right-click the service account, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the service account. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Working with Service Key Providers

A service key provider contains Public Key Infrastructure (PKI) credentials that proxy services use for decrypting inbound SOAP messages and for outbound authentication and digital signatures.

A PKI credential is a private key paired with a certificate that can be used for digital signatures and encryption (for Web Services Security) and for outbound SSL authentication. The certificate contains the public key that corresponds to the private key.

Note:

A single service key provider can contain all the following PKI credentials:

  • A key-pair for digital encryption.

    Proxy services use this key-pair to decrypt inbound SOAP messages that have been encrypted to conform with a Web Services Policy statement. For the service key provider to support digital encryption, the key store that is associated with the PKI credential mapper must contain at least one X.509 certificate that supports encryption.

  • A key-pair for digital signatures.

    Proxy services use this key-pair when its endpoint is a web service and the web service requires clients to sign one or more parts of a SOAP envelope.

  • A key-pair for SSL client authentication (two-way SSL).

    Proxy services use this key-pair to authenticate when acting as a client during an outbound TLS/SSL (Secure Sockets Layer) connection. For example, when routing a message to an HTTPS business service or proxy service that requires client certificate authentication.

You can use the same service key provider for multiple proxy services.

How to Create Service Key Providers

When you associate an encryption key service key provider with a proxy service, Service Bus embeds the X.509 certificate into the proxy service's WSDL file. The proxy service then uses this certificate to encrypt the messages that it sends to its endpoint. The proxy service uses the private key in the PKI credential to decrypt the messages that the endpoint returns.

To create a service key provider:

  1. Do one of the following:

    • For JDeveloper: In the Application Navigator, right-click the project or folder to contain the new service key provider, point to New, and select Service Key Provider.

    • For Oracle Service Bus Console: In the Project Navigator, right-click the project or folder to contain the new service key provider, point to Create, and select Resource. Click Security, then click Service Key Provider, and then click OK.

  2. Enter a unique name for this service key provider, and an optional description.

  3. Click Create or Finish.

    The Service Key Provider Definition Editor appears.

  4. To configure an encryption key, do the following:

    1. Next to Encryption Key, click the Browse icon.

      The Select an alias for Encryption Key window displays the key aliases from the key store that your realm's PKI credential mapper uses.

    2. Enter the password you use to secure access to the key store. (You set this password when you create the keystore.)

    3. Select a key alias that maps to an X.509 certificate and that supports encryption.

    4. Click Submit.

  5. To configure a digital signature key, do the following:

    1. Next to Digital Signature Key, click the Browse icon.

      The Select an alias for Digital Signature Key window displays the key aliases from the key store that your realm's PKI credential mapper uses.

    2. Enter the password you use to secure access to the key store. (You set this password when you create the keystore.)

    3. Select a key alias.

    4. Click Submit.

  6. To configure an SSL client authentication key for two-way SSL, do the following:

    1. Next to SSL Client Authentication Key, click the Browse icon.

      The Select an alias for SSL Client Authentication Key window displays the key aliases from the key store that your realm's PKI credential mapper uses.

    2. Enter the password you use to secure access to the key store. (You set the password when you create the keystore.)

    3. Select a key alias.

    4. Click Submit.

  7. In the toolbar, click Save.

  8. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

How to Edit Service Key Providers

Once you create a service key provider, you can reconfigure the key information.

To edit a service key provider:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the service key provider to edit.
  2. Right-click the service account name, and select Open.
  3. To make a change to the fields, click the icons to the right of the fields to select, remove, or edit a key.

    For information about the fields you can edit, see How to Create Service Key Providers and the online help provided with Service Bus.

  4. When you are done making changes, click Save in the toolbar.
  5. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

How to Delete Service Key Providers

When you delete a service key provider, Service Bus also deletes the associated alias to key-pair bindings from the PKI credential mapping provider. Service Bus does not delete the associated key-certificate pair from the key store. You can delete the service key provider even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

Before you Begin:

If any proxy service is configured to use the service key provider, remove the service key provider from the proxy service. In the Oracle Service Bus Console, open the service key provider in the Service Key Provider Definition Editor and click the Tools icon in the upper right, and then select References to find out if it has any references. In JDeveloper, right-click the service key provider and select Explore Dependencies.

To delete a service key provider:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the service key provider to delete.
  2. Right-click the name of the service key provider, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the service key provider. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Working with Alert Destinations

An alert destination resource defines a list of recipients that can receive alert notifications from Service Bus.

You can configure each alert destination resource to include a set of recipients according to a given context and then associate the resource with the alerts you define. Alert destinations give you the flexibility to specify whether alerts are sent to SNMP traps, collected for reporting, logged to the alert log of the local server , or sent to e-mail recipients or JMS destinations.

When you configure an Alert action in a pipeline, or an SLA alert rule for a service, the configuration includes specifying an alert destination, which defines who receives alerts when they are generated. For email and JMS destinations, a destination resource can include a list of email addresses or JMS URIs, respectively. You can reuse alert destinations across alert configurations.

Alert Destination Types

For each alert destination, you can specify that the alerts be sent to multiple types of destinations, as described in the following sections.

Email

Alert notifications can be sent to multiple emails addresses. To configure an email alert destination, you need an SMTP server global resource or a JavaMail session in Oracle WebLogic Server. When an alert is delivered, email metadata consisting of the details about the alert is prefixed to the details of the payload. For information about SMTP server resources, see Working with SMTP Server Resources. For information about configuring JavaMail sessions, see Configure Access to JavaMail in the Oracle WebLogic Remote Console Online Help.

SNMP Traps

Simple Network Management Protocol (SNMP) traps allow any third-party software to monitor service level agreements within Service Bus. With SNMP notifications enabled, Web Services Management (WSM) and Enterprise Service Management (ESM) tools can monitor SLA violations and pipeline alerts.

SNMP is an application-layer protocol which allows the exchange of information on the management of a resource across a network. It enables you to monitor a resource and, if required, take some action based on the data obtained from the resource. Service Bus supports SNMP version 1 and 2. SNMP includes the following components:

  • Managed Resource

  • Management Information Base (MIB)

  • SNMP Agent

  • SNMP Manager

  • Network Management System (NMS)

Reporting

The Reporting destination lets you send notifications of pipeline alerts and SLA alerts to a custom reporting provider that can be developed using the reporting APIs provided with Service Bus. This allows third parties to receive and process alerts in custom Java code.

Alert Logging

Each alert destination lets you configure whether or not the alerts sent to that destination are logged. Logged alerts are sent to the local alert log. Each Service Bus server has its own alert log. In a cluster, the Admin Server collects the alert logs from all Managed Servers and aggregates the alerts for logging.

JMS

Alert notifications can be sent to one or more Java Messaging Service (JMS) queues or topics. You must configure a JNDI URL for the JMS destination for alerts, create a JMS connection factory and a queue or topic, and target them to the appropriate JMS server in the Oracle WebLogic Remote Console. For information, see Methods for Configuring JMS System Resources in Administering JMS Resources for Oracle WebLogic Server. When you define the JMS alert destination you can either use a destination queue or a destination topic. The message type can be bytes or text. For more information about how to configure JMS alert destinations see How to Define JMS Recipients for an Alert Destination.

How To Create Alert Destinations

Alerts are aggregated at runtime, and you can view them on the Service Bus Dashboard in Fusion Middleware Control.

To create an alert destination:

  1. Do one of the following:

    • For JDeveloper: In the Application Navigator, right-click the project or folder to contain the new alert destination, point to New, and select Alert Destination.

    • For Oracle Service Bus Console: In the Project Navigator, right-click the project or folder to contain the new alert destination, point to Create, and select Resource. Click Miscellaneous, then click Alert Destination, and then click OK.

  2. Enter a unique name for this alert destination, and an optional description.
  3. Click Create or Finish.

    The Alert Destination Definition Editor appears.

  4. Select any of the following destinations to include them in this alert destination resource. In JDeveloper, select Yes to select a destination type.

    • SNMP Trap: Alerts are sent as SNMP traps, and can be processed by any third-party enterprise monitoring systems.

    • Reporting: Alerts are sent to the Service Bus reporting module and can be captured using a custom reporting provider developed using the reporting APIs provided with Service Bus. This allows third-parties to receive and process alerts in custom Java code.

    • Alert Logging: Alerts sent to this alert destination are logged to the alert log.

  5. To add email recipients to the alert destination resource definition, see How to Define Email Recipients for an Alert Destination.
  6. To add JMS destinations to the alert destination resource definition, see How to Define JMS Recipients for an Alert Destination.
  7. Click Save.

How to Define Email Recipients for an Alert Destination

Before you add an email destination, you must configure an SMTP server (see How to Create SMTP Server Resources), or a JavaMail session in WebLogic Server. If there are no SMTP server resources or JavaMail sessions available, configured, you cannot configure an email recipient.

To add or update email recipients in an alert destination:

  1. Create an alert destination, as described in How To Create Alert Destinations.
  2. Above the email Recipients table, click Add.

    In JDeveloper, email configuration fields appear in the bottom of the page. In the Oracle Service Bus Console, the Add email Recipients dialog appears.

  3. In the Mail Recipients field, enter an email recipient in the format mailto:username@hostname.

    To specify multiple email recipients, enter the user names and hostnames in a comma-separated list. For example, mailto:username@hostname[,username_1@hostname_1]...[,username_n@hostname_n]

    Only the first mail recipient needs to be prefixed with the text "mailto:".

  4. To send messages over secure sockets layer (SSL), select SSL Required.
  5. Do only one of the following:

    • To use an SMTP server for outgoing mail, click in the SMTP Server field and select the name of the SMTP server to use.

    • To use a Java Mail session, click in the Mail Session field and select an available mail session.

  6. In the From Name field, enter the sender's name for the alert notification.
  7. In the From Address field, enter the sender's email address.

    This field is required if a value for From Name is specified.

  8. In the Reply To Name field, enter a name to which replies are addressed.
  9. In the Reply To Address field, enter an email address to which replies are sent. This field is required if a value for Reply To Name is specified.
  10. In the Connection Timeout field, enter the number of milliseconds a connection must wait for a response from the server before timing out.
  11. In the Socket I/O Timeout field, enter the number of milliseconds for a socket I/O timeout when waiting for a response from the server.
  12. In the Request Encoding field, enter a character set encoding value.

    The default encoding value is iso-8859-1.

  13. If you are using Oracle Service Bus Console, click OK to close the dialog.
  14. To make changes to an email recipient, select that row in the table and click Edit to the upper right of the table. Modify any of the above fields.
  15. To delete an email recipient, select that row in the table and click Delete to the upper right of the table.
  16. Click Save.

How to Define JMS Recipients for an Alert Destination

While WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see Configure Foreign Servers in the Oracle WebLogic Remote Console Online Help.

To add or update JMS destinations in an alert destination:

  1. Create an alert destination, as described in How To Create Alert Destinations.
  2. Above the JMS Destinations table, click Add.

    In JDeveloper, JMS configuration fields appear in the bottom of the page. In the Oracle Service Bus Console, the Add JMS Destination dialog appears.

  3. In the Destination URI field, enter a JMS destination URI in the format jms://host:port/factoryJndiName/destJndiName.
  4. In the Destination Type field, select Queue or Topic.
  5. In the Message Type field, select Bytes or Text.
  6. In the Request Encoding field, enter a character set encoding value.

    The default encoding value is UTF-8.

  7. If you are using Oracle Service Bus Console, click OK to close the dialog.
  8. To make changes to a JMS destination, select that row in the table and click Edit to the upper right of the table. Modify any of the above fields.
  9. To delete a JMS destination, select that row in the table and click Delete to the upper right of the table.
  10. Click Save.

How to Edit Alert Destinations

Once you create an alert destination you can modify its description, and add, update, or remove email recipients and JMS destinations.

To edit an alert destination:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the alert destination to edit.
  2. Right-click the alert destination name, and select Open.
  3. Modify the description or any of the configuration details:
  4. When you are done making changes, click Save.
  5. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

How to Delete Alert Destinations

When you delete alert destinations, you need to update any alert actions or rules that reference the resource. To delete specific email recipients or JMS destinations from an alert destination, see How to Define Email Recipients for an Alert Destination or How to Define JMS Recipients for an Alert Destination.

Before you Begin:

If the alert destination has any references, remove them before deleting it. In the Oracle Service Bus Console, open the alert destination in the Alert Destination Definition Editor and click the Tools icon in the upper right, and then select References to find out whether there are any references. In JDeveloper, right-click the alert destination and select Explore Dependencies.

To delete an alert destination:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the alert destination to delete.
  2. Right-click the alert destination, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the alert destination. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Working with SNMP

SNMP is an application-layer protocol that allows the exchange of information on the management of a resource across a network. SNMP lets you to monitor a resource and, if required, take an action based on the data obtained from the resource. For more information about SNMP, see Monitoring Oracle WebLogic Server with SNMP.

Guidelines for Working with SNMP Agents for Service Bus

You can create and target SNMP agents in an existing Oracle WebLogic domain to trap SNMP messages generated by Service Bus. For instructions on creating and targeting SNMP agents, see the following topics in the Oracle WebLogic Remote Console Online Help:

  • Create SNMP agents

  • Target SNMP agents

  • Create trap destinations

You can create SNMP agents that are either domain-scoped or server-scoped. Domain-scoped agents, which are targeted to the domain rather than to an individual server, are for backward compatibility and are being deprecated. Oracle recommends that you create server-scoped agents.

When creating and targeting an SNMP server-scoped agent for Service Bus, use the following guidelines:

  • Targeting the Agent: When targeting an SNMP agent to Service Bus, target only the Service Bus Admin Server. Only agents targeted to the Admin Server receive alerts from Service Bus. Agents targeted to Managed Servers do not receive SNMP messages.

  • Creating a Trap Destination: Enter the following settings for the destination:

    • Name: alsbDestination-0

    • Community: weblogic

    • Host and Port: Set the values to point to the host and port where the SNMP manager is listening for these alerts, such as localhost and 163.

How to Start Listening for Traps

You can run a command-line utility to listen for the traps generated within Service Bus.

To start listening for traps:

  1. In a command window, change directories to WL_ORACLE_HOME/server/bin, and run the following command:
    setWLSEnv.cmd(.sh)
  2. Run the following Java command to start the WebLogic Server SNMP command line utility, which listens for traps and prints them on the server console (using 163 as the listen port for traps):
    java weblogic.diagnostics.snmp.cmdline.Manager SnmpTrapMonitor -p 163

    From then on, the generated traps should reach the running command line utility.

    Note:

    On Solaris, port numbers 0 to 1023 are reserved for root login. If you want to use ports 161 and 163 (as used in this procedure), you may have to start the server and command line utility using root login. To avoid this problem, and to avoid using the root login, specify port numbers above 1023 for both the SNMP agent and the SNMP manager command.

Working with XML Schemas

Schemas describe types for primitive or structured data. XML schemas are an XML vocabulary that describes the rules XML business data must follow. XML schemas specify the structure of documents, and the data type of each element and attribute contained in the document.

You use XML schemas as references for WSDL resources and to validate an element specified with an XPath expression in a pipeline. For more information, see Adding Validate Actions in JDeveloper.

How to Create XML Schemas

XML schemas are a standard feature in JDeveloper. For information about the editors and tools you use to create XML schemas, see Developing Applications Using XML in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, you can create XML schemas by importing them or by creating an XML schema resource. For more information on importing, see Importing and Exporting Resources and Configurations . Use the following procedure to manually create XML schema resources.

To create an XML schema in the Oracle Service Bus Console:

  1. In the Project Navigator, right-click the project or folder to contain the new XML schema, point to Create, and select Resource. Click Interfaces, then click Schema, and then click OK.

    The Create Schema dialog appears.

  2. Do one of the following:

    • To create the resource from an existing schema file, click Browse next to the File Upload field and then navigate to and select the file to use.

      The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.

    • To create a new XML schema, enter a unique name for the XML schema resource.

  3. Optionally, enter a brief description of the resource.

  4. Click Create.

    The XML schema elements, if defined, appear in the Schema Definition Editor.

  5. To modify the schema, do the following:

    1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

    2. To browse to and select a new schema file to upload, click Browse.

    3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

    4. Click Save.

  6. In the Schema Definition Editor toolbar, click Save.

  7. To end the session and deploy the configuration to the runtime, click Activate.

How to Edit XML Schemas

XML schemas are a standard feature in JDeveloper. For information about editing XML schemas, see Developing Applications Using XML in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, use the following procedure to edit XML schemas.

To edit an XML schema in the Oracle Service Bus Console:

  1. In the Project Navigator, expand the project and folders containing the XML schema to edit.
  2. Right-click the XML schema name, and select Open.
  3. Click Edit Source in the toolbar.

    The Edit Source dialog appears.

  4. To browse to and select a new XML schema file to upload, click Browse.
  5. To modify the contents of the file, update the code directly in the Contents section of the dialog.
  6. Click Save.
  7. In the Schema Definition Editor toolbar, click Save.
  8. To end the session and deploy the configuration to the runtime, click Activate.

How to Delete XML Schemas

If any resources reference the XML schema you want to delete, remove those references before deleting the XML schema. In the Oracle Service Bus Console, open the XML schema in the Schema Definition Editor and click the Tools icon in the upper right, and then select References to find out if it has any references. In JDeveloper, right-click the XML schema and select Explore Dependencies.

You can delete the XML schema even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

To delete an XML schema:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the XML schema to delete.
  2. Right-click the name of the schema, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the schema. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Working with XML Documents

XML document resources store XML files for use in proxy or business service configurations.

For example, you can create XML document resources for TopLink mapping files needed in JCA proxy or business services that communicate with JCA-compliant systems.

For more information about JCA services, see Using the JCA Transport and JCA Adapters.

How to Create XML Documents

XML documents are a standard feature in JDeveloper. For information about the editors and tools you use to create XML files, see Developing Applications Using XML in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, the easiest way to create XML documents is to use the import feature. For example, if you import JCA resources (JCA file, associated WSDL file, and TopLink mapping file), Service Bus automatically generates XML document resources out of mapping files and maintains the dependencies among resource files. For more information on importing, see Importing and Exporting Resources and Configurations .

If you do not bulk import, use the following procedure to manually create XML documents.

To create XML documents in the Oracle Service Bus Console:

  1. In the Project Navigator, right-click the project or folder to contain the new XML document, point to Create, and select Resource. Click Miscellaneous, click XML Document, and then click OK.

    The Create XML Document dialog appears.

  2. Do one of the following:

    • To create the resource from an existing XML file, click Browse next to the File Upload field and then navigate to and select the XML file to use.

      The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.

    • To create a new XML document for the resource, enter a unique name for the XML document resource.

  3. Optionally, enter a brief description of the resource.

  4. Click Create.

    The XML document appears in the XML Document Definition Editor.

  5. To modify the XML code, do the following:

    1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

    2. To browse to and select a new XML file to upload, click Browse.

    3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

    4. Click Save.

  6. In the XML Document Definition Editor toolbar, click Save.

  7. To end the session and deploy the configuration to the runtime, click Activate.

How to Edit XML Documents

XML documents are a standard feature in JDeveloper. For information about editing XML files, see Developing Applications Using XML in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, use the following procedure to edit XML files.

To edit an XML document in the Oracle Service Bus Console:

  1. In the Project Navigator, expand the project and folders containing the XML document to edit.
  2. Right-click the XML document name, and select Open.
  3. Click Edit Source in the toolbar.

    The Edit Source dialog appears.

  4. To browse to and select a new XML file to upload, click Browse.
  5. To modify the contents of the file, update the code directly in the Contents section of the dialog.
  6. Click Save.
  7. In the XML Document Definition Editor toolbar, click Save.
  8. To end the session and deploy the configuration to the runtime, click Activate.

How to Delete XML Documents

If any resources, such as JCA bindings, reference the XML document you want to delete, remove those references before deleting the XML document. In the Oracle Service Bus Console, open the XML document in the XML Document Definition Editor and click the Tools icon in the upper right, and then select References to find out if it has any references. In JDeveloper, right-click the XML document and select Explore Dependencies.

To delete an XML document:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the XML document to delete.
  2. Right-click the name of the document, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the XML document. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

Working with JAR Files

A JAR (Java Archive) is a zipped file that contains a set of Java classes. JAR files store the compiled Java classes and associated metadata that can constitute a program. A JAR file acts like a callable program library for Java code elements so a single compilation link provides access to multiple elements, rather than requiring bindings for each element individually.

To use JAR files in a Service Bus project, you upload them to JAR resources. JAR files in Service Bus are used in:

  • Java callout actions

  • EJB-based business services

  • JEJB services

  • Tuxedo-based proxy and business services

How to Add JAR Files

JAR file integration is a standard feature in JDeveloper. For information about adding JAR files and libraries to your Service Bus projects, see How to Manage Libraries in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, you can add JAR files by either importing them into a Service Bus project or uploading them into archive resources. For more information on importing, see Importing and Exporting Resources and Configurations . Use the procedure below to upload a JAR file into an archive resource.

To add a JAR file using the Oracle Service Bus Console:

  1. In the Project Navigator, right-click the project or folder to contain the new JAR file, point to Create, and select Resource. Click Miscellaneous, then click Archive, and then click OK.

    The Create Archive dialog appears.

  2. Click Browse next to the File Upload field and then navigate to and select the JAR file to upload.

    The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.

  3. Optionally, enter a brief description of the resource.

  4. Click Create.

    The configuration details and dependencies for the JAR file appear in the Archive Definition Editor.

  5. To add dependencies, do the following:

    1. Click Add above the dependencies table.

      A new row appears in the table.

    2. Click in the new row in the name column, and then click Browse.

      The Search and Select dialog appears.

    3. Enter a file name or the path to the file, and click Search.

    4. In the results list, select the name of the file containing the dependency, and then click OK.

  6. Repeat the above steps for each dependency to add. Use the up and down arrows above the Dependencies table to re-order the list of dependencies.

  7. In the Archive Definition Editor toolbar, click Save.

  8. To end the session and deploy the configuration to the runtime, click Activate.

How to Update a JAR File

Updating an archive resource essentially involves pointing the resource to a new version of the JAR file or to a different JAR file, as you cannot edit a JAR using Service Bus. JAR file integration is a standard feature in JDeveloper. For information about updating JAR files, see How to Manage Libraries in Developing Applications with Oracle JDeveloper.

If you are using the Oracle Service Bus Console, use the following procedure to update a JAR file in an archive resource.

Caution:

If you update the JAR file used by an EJB business service by updating to a newer version of the file, you must redeploy the EJB, edit any EJB service that uses the JAR file, and reselect the JAR resource, save, and activate. This repackages the EJB business service to use the new JAR.

Java callout actions and Tuxedo-based services automatically pick up the new JAR file.

To update a JAR file in the Oracle Service Bus Console:

  1. In the Project Navigator, expand the project and folders containing the archive resource to edit.

  2. Right-click the archive resource name, and select Open.

  3. To update the JAR file, do the following:

    1. Click Upload New JAR File in the toolbar.

      The Upload New JAR File dialog appears.

    2. Click Browse, and then navigate to and select the new JAR file to use.

    3. Click Save.

      The information on the Archive Definition Editor is updated with the new JAR file configuration.

  4. To add a dependency, do the following:

    1. Click Add above the dependencies table.

      A new row appears in the table.

    2. Click in the new row in the name column, and then click Browse.

      The Search and Select dialog appears.

    3. Enter a file name or the path to the file, and click Search.

    4. In the results list, select the name of the file containing the dependency, and then click OK.

  5. To delete a dependency, select the row in the Dependencies table that contains the dependency, and then click Delete.

    The row is removed.

  6. To re-order the dependencies, use the up and down arrows above the table.

  7. When you are done updating the archive resource, click Save in the Archive Definition Editor toolbar.

  8. To end the session and deploy the configuration to the runtime, click Activate.

How to Modify JAR File Dependencies

Service Bus provides additional JAR file features in JDeveloper to let you modify JAR file dependencies. If you are using Oracle Service Bus Console, modify dependencies as described in How to Update a JAR File.

To modify JAR file dependencies in JDeveloper:

  1. In the Application Navigator, find the JAR file whose dependencies you want to modify.
  2. Right-click the name of the file, point to Service Bus and select Modify JAR Dependencies.

    The Modify JAR Dependencies dialog appears.

  3. To add dependencies, move JAR files from the Available JARs pane to the JAR References pane.
  4. To remove dependencies, move JAR files from the JAR References pane to the Available JARs pane.
  5. Click OK when you are done.

How to Delete a JAR File

If any resources reference the JAR file you want to delete, remove those references before deleting the archive resource. In the Oracle Service Bus Console, open the archive resource in the Archive Definition Editor and click the Tools icon in the upper right, and then select References to find out whether it has any references. In JDeveloper, right-click the JAR file and select Explore Dependencies.

You can delete the JAR file even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

To delete a JAR file:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the archive resource for the JAR file to delete.
  2. Right-click the name of the resource, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the JAR file. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.