(For more resources related to this topic, see here.)
The WSDL of a web service is made up of the following XML artifacts:
WSDL Definition: It defines the various operations that constitute a service, their input and output parameters, and the protocols (bindings) they support.
XML Schema Definition (XSD): It is either embedded within the WSDL definition or referenced as a standalone component; this defines the XML elements and types that constitute the input and output parameters.
To better facilitate the exchange of data between services, as well as achieve better interoperability and re-usability, it is good practice to de?ne a common set of XML Schemas, often referred to as the canonical data model, which can be referenced by multiple services (or WSDL De?nitions).
This means, we will need to share the same XML schema across multiple composites. While typically a service (or WSDL) will only be implemented by a single composite, it will often be invoked by multiple composites; so the corresponding WSDL will be shared across multiple composites.
Within JDeveloper, the default behavior, when referencing a predefined schema or WSDL, is for it to add a copy of the file to our SOA project.
However, if we have several composites, each referencing their own local copy of the same WSDL or XML schema, then every time that we need to change either the schema or WSDL, we will be required to update every copy.
This can be a time-consuming and error-prone approach; a better approach is to have a single copy of each WSDL and schema that is referenced by all composites.
The SOA infrastructure incorporates a Metadata Service (MDS), which allows us to create a library of XML artifacts that we can share across SOA composites. MDS supports two types of repositories:
File-based repository: This is quicker and easier to set up, and so is typically used as the design-time MDS by JDeveloper.
Database repository: It is installed as part of the SOA infrastructure. This is used at runtime by the SOA infrastructure.
As you move projects from one environment to another (for example, from test to production), you must typically modify several environment-specific values embedded within your composites, such as the location of a schema or the endpoint of a referenced web service. By placing all this information within the XML artifacts deployed to MDS, you can make your composites completely agnostic of the environment they are to be deployed to.
The other advantage of placing all your referenced artifacts in MDS is that it removes any direct dependencies between composites, which means that they can be deployed and started in any order (once you have deployed the artifacts to MDS).
In addition, an SOA composite leverages many other XML artifacts, such as fault policies, XSLT Transformations, EDLs for event EDN event definitions, and Schematrons for validation, each of which may need to be shared across multiple composites. These can also be shared between composites by placing them in MDS.
Defining a project structure
Before placing all our XML artifacts into MDS, we need to define a standard file structure for our XML library. This allows us to ensure that if any XML artifact within our XML library needs to reference another XML artifact (for example a WSDL importing a schema), it can do so via a relative reference; in other words, the XML artifact doesn’t include any reference to MDS and is portable. This has a number of benefits, including:
OSB compatibility; the same schemas and WSDLs can be deployed to the Oracle Service Bus without modification
Third-party tool compatibility; often we will use a variety of tools that have no knowledge of MDS to create/edit XML schemas, WSDLs, and so on (for example XML Spy, Oxygen)
In this article, we will assume that we have defined the following directory structure under our
Under the xmllib folder, we have defined multiple
However, it is also likely that there will be a number of XML artifacts that need to be shared between different solutions (for example, the canonical data model for the organization), which in this example would go under
Where we have XML artifacts shared between multiple solutions, appropriate governance is required to manage the changes to these artifacts.
For the purpose of this article, the directory structure is over simpli?ed. In reality, a more comprehensive structure should be de?ned as part of the naming and deployment standards for your SOA Reference Architecture.
The other consideration here is versioning; over time it is likely that multiple versions of the same schema, WSDL and so on, will require to be deployed side by side. To support this, we typically recommend appending the version number to the filename.
We would also recommend that you place this under some form of version control, as it makes it far simpler to ensure that everyone is using an up-to-date version of the XML library. For the purpose of this article, we will assume that you are using Subversion.
Creating a file-based MDS repository for JDeveloper
Before we can reference this with JDeveloper, we need to define a connection to the file-based MDS.
By default, a file-based repository is installed with JDeveloper and sits under the directory structure:
This already contains the subdirectory soa, which is reserved for, and contains, artifacts used by the SOA infrastructure
For artifacts that we wish to share across our applications in JDeveloper, we should create the subdirectory apps (under the seed directory); this is critical, as when we deploy the artifacts to the SOA infrastructure, they will be placed in the apps namespace
We need to ensure that the content of the apps directory always contains the latest version of our XML library; as these are stored under Subversion, we simply need to check out the right portion of the Subversion project structure.
How to do it…
First, we need to create and populate our file-based repository. Navigate to the seed directory, and right-click and select SVN Checkout…, this will launch the Subversion Checkout window.
For URL of repository, ensure that you specify the path to the apps subdirectory.
For Checkout directory, specify the full pathname of the seed directory and append /apps at the end. Leave the other default values, as shown in the following screenshot, and then click on OK:
Subversion will check out a working copy of the apps subfolder within Subversion into the seed directory.
Before we can reference our XML library with JDeveloper, we need to define a connection to the file-based MDS.
Within JDeveloper, from the File menu select New to launch the Gallery, and under Categories select General | Connections | SOA-MDS Connection from the Items list.
This will launch the MDS Connection Wizard.
Enter File Based MDS for Connection Name and select a Connection Type of File Based MDS.
We then need to specify the MDS root folder on our local filesystem; this will be the directory that contains the apps directory, namely:
Click on Test Connection; the Status box should be updated to Success!. Click on OK. This will create a file-based MDS connection in JDeveloper.
Browse the File Based MDS connection in JDeveloper.
Within JDeveloper, open the Resource Palette and expand SOA-MDS. This should contain the File Based MDS connection that we just created.
Expand all the nodes down to the xsd directory, as shown in the following screenshot:
If you double-click on one of the schema files, it will open in JDeveloper (in read-only mode).
Once the apps directory has been checked out, it will contain a snapshot of the MDS artifacts at the point in time that you created the checkpoint. Over time, the artifacts in MDS will be modified or new ones will be created. It is important that you ensure that your local version of MDS is updated with the current version.
To do this, navigate to the seed directory, right-click on apps, and select SVN Update.
Creating Mediator using a WSDL in MDS
In this recipe, we will show how we can create Mediator using an interface definition from a WSDL held in MDS. This approach enables us to separate the implementation of a service (a composite) from the definition of its contract (WSDL).
Make sure you have created a file-based MDS repository for JDeveloper, as described in the first recipe. Create an SOA application with a project containing an empty composite.
How to do it…
Drag Mediator from SOA Component Palette onto your composite. This will launch the Create Mediator wizard; specify an appropriate name (EmployeeOnBoarding in the following example), and for the Template select Interface Definition from WSDL
Click on the Find Existing WSDLs icon (circled in the previous screenshot); this will launch the SOA Resource Browser. Select Resource Palette from the drop-down list (circled in the following screenshot).
Select the WSDL that you wish to import and click on OK. This will return you to the Create Mediator wizard window; ensure that the Port Type is populated and click on OK.
This will create Mediator based on the specified WSDL within our composite.
How it works…
When we import the WSDL in this fashion, JDeveloper doesn’t actually make a copy of the schema; rather within the componentType file, it sets the wsdlLocation attribute to reference the location of the WSDL in MDS (as highlighted in the following screenshot).
For WSDLs in MDS, the wsdlLocation attribute uses the following format:
Where oramds indicates that it is located in MDS, apps indicates that it is in the application namespace and
The wsdlLocation doesn’t specify the physical location of the WSDL; rather it is relative to MDS, which is specific to the environment in which the composite is deployed.
This means that when the composite is open in JDeveloper, it will reference the WSDL in the file-based MDS, and when deployed to the SOA infrastructure, it will reference the WSDL deployed to the MDS database repository, which is installed as part of the SOA infrastructure.
This method can be used equally well to create a BPEL process based on the WSDL from within the Create BPEL Process wizard; for Template select Base on a WSDL and follow the same steps.
This approach works well with Contract First Design as it enables the contract for a composite to be designed first, and when ready for implementation, be checked into Subversion.
The SOA developer can then perform a Subversion update on their file-based MDS repository, and then use the WSDL to implement the composite
Creating Mediator that subscribes to EDL in MDS
In this recipe, we will show how we can create Mediator that subscribes to an EDN event whose EDL is defined in MDS. This approach enables us to separate the definition of an event from the implementation of a composite that either subscribes to, or publishes, the event.
Make sure you have created a file-based MDS repository for JDeveloper, as described in the initial recipe.
Create an SOA application with a project containing an empty composite.
How to do it…
Drag Mediator from SOA Component Palette onto your composite. This will launch the Create Mediator wizard; specify an appropriate name for it (UserRegistration in the following example), and for the Template select Subscribe to Events.
Click on the Subscribe to new event icon (circled in the previous screenshot); this will launch the Event Chooser window.
Click on the Browse for Event Definition (edl) files icon (circled in the previous screenshot); this will launch SOA Resource Browser. Select Resource Palette from the drop-down list.
Select the EDL that you wish to import and click on OK. This will return you to the Event Chooser window; ensure that the required event is selected and click on OK.
This will return you to the Create Mediator window; ensure that the required event is configured as needed, and click on OK.
This will create an event subscription based on the EDL specified within our composite.
How it works…
When we reference an EDL in MDS, JDeveloper doesn’t actually make a copy of the EDL; rather within the composite.xml file, it creates an import statement to reference the location of the EDL in MDS.
This approach can be used equally well to subscribe to an event within a BPEL process or publish an event using either Mediator or BPEL.