3 Getting Started with Oracle Service Bus in JDeveloper

This chapter provides general information about how to use Service Bus in JDeveloper to configure services and other service bus resources. These are design-time activities that, except where noted, do not require a running WebLogic Server instance.

This chapter includes the following topics:

• JDeveloper Concepts for Service Bus

• Managing Service Bus Components in JDeveloper

• Creating Service Bus Applications and Projects in JDeveloper

• Refactoring Service Bus Projects, Folders, and Resources

For complete information on using JDeveloper, see Developing Applications with Oracle JDeveloper.

3.1 JDeveloper Concepts for Service Bus

Service Bus uses editors, wizards, and dialogs in JDeveloper to create and configure Service Bus applications. Some of these are specific to Service Bus components, and some are standard JDeveloper tools. For example, proxy service and business service editors are specific to Service Bus, but XSLT and XQuery mappers are shared by other products in JDeveloper. Service Bus shares many features with SOA Suite components in JDeveloper.

The following figure shows Service Bus artifacts in JDeveloper, including project files in the application navigator, the Service Bus Overview Editor in the center, and the Components window on the right. The Service Bus Overview Editor is where you define services and message flows. The Components window lists all the different Service Bus and SOA Suite components you can drag onto the Overview Editor design canvas.

Figure 3-1 Oracle Service Bus in JDeveloper

Description of "Figure 3-1 Oracle Service Bus in JDeveloper"

3.1.1 Application Navigator

The Application Navigator displays the key files for all the resources and services included in the Service Bus project, which can include the following:

• An XML file that is automatically created when you create a Service Bus project. This file describes the entire Service Bus application, including services, resources, references, and wires. In the Application Navigator, this file has the same name as the project. In the file system, it is named servicebus.sboverview.

• Any proxy service files (service_name.proxy).

• Any business service files (service_name.bix).

• Pipeline files (pipeline_name.pipeline).

• Split-join files (splitjoin_name.flow).

• Any resource files, such as service accounts, WSDL files, service key providers, alert destinations, and so on.

• Additional subfolders for class files, XSD files (schemas), and XSL files (transformations).

3.1.2 Service Bus Overview Editor

The Service Bus Overview Editor lets you design your Service Bus application from the top down in a graphical view of the components included in the application. You drag pipelines, split-joins, transports, adapters, and bindings from the Components window into the designer window of the editor. When you drag and drop a component into the designer window, a corresponding wizard appears so you can perform basic configuration tasks related to that component. For example, when you drag and drop a pipeline to the Pipelines/Split Joins section of the editor, the Create Pipeline Service wizard appears. After you complete the wizard, the component appears in the editor, and you can double-click the component to open its editor and further define its configuration. The following figure shows the Overview Editor with a mixture of services, pipelines, and split-joins.

Figure 3-2 Service Bus Overview Editor

Description of "Figure 3-2 Service Bus Overview Editor"

3.1.3 Resource Editors

Each type of Service Bus resource can be configured in an editor that is specific to that resource. Most editors have multiple views, which you select in the lower left corner of the editor. The Configuration view is available for most resources, and is where you do most of the resource configuration. Design view is available for the Service Bus Overview Editor, pipelines, and split-joins, and provides a graphical representation of how messages are processed. In design mode, you can drag and drop activities from the Components window directly into a split-join or pipeline. For some resources, you can view the source code using the Source view. Several editors also include a History view, where you can look at a history of changes to the displayed resource. The following figure shows the General configuration page of the Proxy Service Definition Editor.

Figure 3-3 Proxy Service Definition Editor in JDeveloper

Description of "Figure 3-3 Proxy Service Definition Editor in JDeveloper"

3.1.4 Components Window

The Components window appears when the Service Bus Overview Editor, the Pipeline Editor, or the Split-Join Editor is open. The Components window lists the various components that you can use in a Service Bus application, pipeline, or split-join, depending on which editor is visible. For the overview editor, the Components window displays the components you can add to the application, including resources, adapters, and transports. For pipelines and split-joins, the Components window displays routing, transformation, and error handling actions that you can use to define the flow of data between services.

The elements listed in the Components window can be dragged and dropped from the Components window to the visible editor. If the Components window is not visible, select Components from the Window main menu. The following figure shows the Components window for the Service Bus Overview Editor.

Figure 3-4 Service Bus Components Window

Description of "Figure 3-4 Service Bus Components Window"

3.1.5 Resources Window

When you select an item in the Resources window, a dialog appears in which you can browse both local and remote resources. For example, you can access the following resources:

• Shared local application metadata such as schemas, WSDL files, event definitions, business rules, and so on.

• WSIL browser functionality that uses remote resources that can be accessed through an HTTP connection, file URL, or Application Server connection.

• Remote resources that are registered in a Universal Description, Discover, and Integration (UDDI) registry.

If the Resources window is not visible, select Resources from the Window main menu.

3.1.6 Properties Window

The Properties window displays properties for the selected Service Bus resource or component, and lets you modify the properties for pipeline actions and split-join operations. For information about the properties you can configure, see the online help for Service Bus and the following chapters in this guide:

• Improving Service Performance with Split-Join

• Working with Pipeline Actions in Oracle Service Bus Console

If the Property Inspector is not visible, select Property Inspector from the Window main menu.

3.1.7 Structure View

The Structure window offers a structural view of the component currently displayed in the editor. Depending on the document currently open, the Structure Window lets you view data in two modes, as indicated by the tabs near the bottom of this window:

• Source mode displays the code structure of the file currently open in the editor. This is applicable to technologies that allow code editing, such as XML. For example, this tab will not be available when a pipeline is open for editing.

• Design mode displays the tree structure of the file currently open in the editor, and lets you navigate through the different nodes of the component.

The Structure window is dynamic, always tracking the current selection of the active

3.1.8 Log Window

The Log window displays messages about application compilation, validation, and deployment.

3.2 Managing Service Bus Components in JDeveloper

In JDeveloper, Service Bus components are contained within a Service Bus project, and Service Bus projects can be gathered into Service Bus applications. The resources are stored as files in the file system. All resources (such as services, WSDL files, XQuery transformations, and so on) reside in one non-overlapping project.

You create resources directly under a project or in folders within the project to organize them further. Each folder contains a set of resources and can also contain additional folders, like directories in a file system. Resources located in one project can reference and use resources that are defined in other projects. You can move resources between projects or folders, and rename or delete them. Service Bus preserves dependencies when resources are renamed or moved, and also adjusts any references to a renamed or moved resource.

3.3 Creating Service Bus Applications and Projects in JDeveloper

In JDeveloper, Service Bus resources are organized into projects, which can be further divided into folders. Service Bus projects are grouped into Service Bus applications.

Note:

To create and deploy Service Bus applications and projects in JDeveloper, you must install the Service Bus extension. For instructions on installing this extension for JDeveloper, see Enabling Oracle JDeveloper Extensions in Installing Oracle JDeveloper.

3.3.1 Guidelines for Creating Applications and Projects

Make sure to follow these guidelines when you create Service Bus applications and projects in JDeveloper.

• When you create applications and projects, you can specify the directory in which the associated files are stored. You must create Service Bus projects in the same folder as their containing application.

• Do not create application or project names with spaces.

• Do not create applications and projects in directory paths that have spaces (for example, c:\Program Files).

• The combination of application and component name cannot exceed 500 characters.

• A project deployed to the same infrastructure must have a unique name across Service Bus applications. For example, do not perform the actions described in Table 3-1. During deployment, the second deployed project overwrites the first deployed project.

  Table 3-1 Restrictions on Naming a Service Bus Project

  Create an Application Named...	With a Project Named...
  Application1	Project1
  Application2	Project1

Caution:

Do not create SOA Tier components in Service Bus applications, nor Service Bus Tier components in SOA Suite applications. Mixing technologies within an application will result in errors.

3.3.2 How to Create a Service Bus Application and Project

The first steps in building a new application are to assign it a name and to specify the directory in which to save source files. By creating an application using application templates provided by JDeveloper, you automatically get the organization of the workspace into projects, along with the project overview file.

You can create a Service Bus application with a Service Bus project, or you can create just the application and create the project separately. The following figure shows the creation wizard when you create the application and project together.

Figure 3-5 Create Service Bus Application with Service Bus Project Wizard

Description of "Figure 3-5 Create Service Bus Application with Service Bus Project Wizard"

3.3.2.1 Creating a Service Bus Application with No Project

Before you begin:

To avoid errors, become familiar with the information in Guidelines for Creating Applications and Projects before creating applications or projects.

To create a Service Bus application with no project:

1. Start Oracle JDeveloper Studio Edition.
2. Do one of the following to create a new Service Bus application:

   • If no applications are open, click New Application in the Application Navigator.

   • In the JDeveloper toolbar, click File, point to New, and select Applications.

   • In the JDeveloper toolbar, click Application and then select New.

   The New Gallery opens, where you can select different application components to create.

3. In the Categories tree, select General > Applications.
4. In the Items pane, select Service Bus Application, and click OK.

   The Create Service Bus Application wizard appears.

5. On the Name your Application page, optionally change the name and directory location for the application.
6. Click Finish.
7. From the File main menu, select Save All.
8. To add projects to your application, see "To add a Service Bus project to a Service Bus application:"

3.3.2.2 Creating a Service Bus Application and Project

Before you begin:

To avoid errors, become familiar with the information in Guidelines for Creating Applications and Projects before creating applications or projects.

To create a Service Bus application and project:

1. Start Oracle JDeveloper Studio Edition.
2. Do one of the following to create a new Service Bus application:

   • If no applications are open, click New Application in the Application Navigator.

   • In the JDeveloper toolbar, click File, point to New, and select Applications.

   • In the JDeveloper toolbar, click Application and then select New.

   The New Gallery opens, where you can select different application components to create.

3. In the Categories tree, select General > Applications.
4. In the Items pane, select Service Bus Application with Service Bus Project, and click OK.

   The Create Service Bus Application wizard appears.

5. On the Name your Application page, optionally change the name and location for the application.
6. On the Name your Project page, optionally change the name of your Service Bus project. Make sure the project directory is in the application directory (this is the default).
7. Click Finish.

   JDeveloper adds the Service Bus project technology, the project's XML file that describes the Service Bus application, and the necessary libraries to your project.

8. From the File main menu, select Save All.

3.3.2.3 Adding a Service Bus Project to a Service Bus Application

Before you begin:

To avoid errors, become familiar with the information in Guidelines for Creating Applications and Projects before creating applications or projects.

To add a Service Bus project to a Service Bus application:

Note:

The following instructions are for the first time you create a Service Bus project. You can continue to follow these steps for future project, but a Project option will also appear when you right-click in the Application Navigator and select New.

1. Start Oracle JDeveloper Studio Edition.
2. Using the Application menu, open the Service Bus application.
3. Click File, point to New, and then select Project.

   The New Gallery dialog appears.

4. In the Categories panel, scroll down to and select Service Bus Tier.
5. In the Items panel, select Service Bus Project, and click OK.

   The Create Service Bus Project wizard appears.

6. On the Name your Project page, you can optionally change the name for your Service Bus project. Leave the directory at its default value, which is located in the containing application's folder.
7. Click Finish.

   JDeveloper adds the Service Bus project technology, the project's XML file that describes the Service Bus application, and the necessary libraries to your project.

8. From the File main menu, select Save All.

3.4 Refactoring Service Bus Projects, Folders, and Resources

You can rename, move, and delete Service Bus resources in JDeveloper using JDeveloper's refactoring features. You can also rename and move folders. Refactoring maintains references between the resources you change, except when you delete a resource or folder. Refactoring also moves, renames, or deletes the resource files and updates information in the Service Bus Overview Editor. In addition to JDeveloper's refactoring features, Service Bus lets you clone a project or folder to a different location.

You can rename and delete resources from the Application Navigator or from the Service Bus Overview Editor. This section describes the Application Navigator steps. For information on refactoring in the Overview Editor, see How to Rename Components in the Service Bus Overview Editor and How to Delete Components in the Service Bus Overview Editor.

3.4.1 How to Rename a Service Bus Folder or Resource in JDeveloper

When you rename Service Bus components, any references are automatically updated.

Note:

If you rename a business service imported from the UDDI registry, the service will become detached from the registry.

To rename a folder or resource:

1. In the Application Navigator, right-click the folder or resource you want to rename.

2. Point to Refactor and click Rename.

3. For resources, do the following:

   1. In the Rename To field of the Rename dialog, enter a new name for the resource. Do not change the file extension.

   2. If the resource is referenced by another resource, click Show Usages to view those references.

   3. Click OK to finalize the new name.

4. For folders, do the following:

   1. In the Name field of the Rename Directory dialog, enter the full path and a new name for the folder.

   2. To view a list of files before confirming the change, select Preview.

   3. Click OK.

   4. If you selected Preview, review the list of files in the Rename Directory Log. Click Refactor to complete the change.

5. In the JDeveloper toolbar, click Save All.

3.4.2 How to Move a Service Bus Folder or Resource in JDeveloper

When you move resources to a different location, Service Bus retains any dependencies against that resource. If you move a project into another project, Service Bus converts it to a folder within the second project.

To move a folder or resource:

1. In the Application Navigator, right-click the project, folder, or resource you want to move.
2. Point to Refactor and click Move.
3. For resources, do the following:

   • If the resource is referenced by another resource, click Show Usages to view those references.

   • In the Move To field of the Move dialog, enter the new directory path for the resource or click Browse to navigate to and select a new directory.

   • Click OK.

4. For folders, do the following:

   • In the Move Directory dialog, navigate to and select the new location for the folder.

   • Click Select.

5. In the JDeveloper toolbar, click Save All.

3.4.3 How to Delete a Project or Resource:

When you delete a project, all resources under the project are deleted. If any resources under this folder are referenced by resources under a different project or folder, you can still delete it but this might result in conflicts due to unresolved references to the deleted resource.

Caution:

If you delete a project or folder that contains a pipeline template resource, all the concrete pipelines derived from that template are unlinked.

3.4.3.1 Deleting a Resource

To delete a resource:

1. In the Application Navigator, right-click the project, folder, or resource you want to delete.
2. Point to Refactor and click Delete.
3. If the resource is referenced by another resource, click Show Usages to view those references.
4. Click Yes to delete the resource.

3.4.3.2 Deleting a Project

To delete a project:

1. In the Application Navigator, right-click the project you want to delete.
2. Click Delete.
3. Select whether to just remove the project from the application or to also delete all of its files and directories from the file system.
4. Click Yes.
5. On the Confirmation Dialog, click Yes.

3.4.4 How to Clone a Project or Folder:

Cloning a project or folder copies all resources in a project or folder to a different location. Service Bus preserves dependencies when an object is cloned and also adjusts any references. For information on clone processing, see What Happens When You Clone a Project and What Happens When You Clone a Folder.

To clone a project or folder:

1. In the Application Navigator, right-click the project, folder, or resource you want to clone.
2. Point to Service Bus and click Clone.
3. On the Select Clone Target dialog, enter a name for the cloned component.
4. Do one of the following:

   • To clone this project or folder as a project, select As project.

   • To clone this project or folder as a folder, select As folder in location and then select the project or folder where you want to locate the cloned project.

5. Click OK.