Last Wednesday the Open Group made available their SOA Source Book.  They describe it as “a collection of source material produced by the SOA Working Group for use by enterprise architects working with Service-Oriented Architecture”.  Having looked at it I have to say it seems to have a high information density and would be a good place to start getting someone's head around SOA concepts.  Well worth a look.

The Problem

The native format builder wizard in the file adapter is great at reading flat file structures but doesn’t support reading more structured file structures.  Sometimes we need to read more complex structures such as master-detail records.  Let’s look at how we can use the file adapter to read structured file formats.

For example imagine a laundry list file such as the one below:

P,101,James L,Shirt,2,Starch L,Socks,6,De-odorise L,Pants,2,Remove Stains

P,220,JoJo L,Sweatshirt,1,Handwash L,Shirt,3,No Iron L,Socks,2,Iron L,Pants,2,Steam Press L,Tie,1,Dry clean

P,305,Ruth L,Skirt,7,Iron Pleats L,Socks,8,Iron

To make it easier to see the record structure I have put boxes around the individual records.  This can be represented in XML as shown below

The native format builder wizard would either treat each line as either the same type of record (“Multiple records are of single type”) or as two different types of record (“Multiple records are of different types”).

In the first case we would have a single record type with four fields that fails to distinguish between people (lines pre-fixed with ‘P’) and laundry items (lines pre-fixed with ‘L’).  This does not reflect the fact that the two lines are of different types.  The second case, multiple records are of different types, is closer to what we want.  It creates two records types, the type being determined by the value of the first field.  The XML for this is shown below:

However this case creates a list of two record types with no recognition that one record is nested inside the other.

Comparing the two XML representations we can see what needs to be done; we need to add an Items element under Room and move the Item element to be under Items.  The question is how do we describe this using the native schema constructs supported by the file adapter.

Creating a Master-Detail Records Native Format Schema

The easiest way to deal with this is to use the native format builder wizard in the file adapter to create the basic outline of the records for us.  We choose “Multiple records are of different types” and provide appropriate names for the two records types and individual fields within the records.

Having created the basic native format schema we can now edit it to be exactly the way we want it for the laundry list.

We make the following changes in the generated native schema file:

• Replace the <choice> element by a <sequence> element.  In conjunction with other changes this will give us a list of elements of the same type, rather than of list of elements of two different types.

  • <xsd:choice minOccurs="1" maxOccurs="unbounded"     nxsd:choiceCondition="terminated"     nxsd:terminatedBy=",">     … </xsd:choice>

    <xsd:sequence>    … </xsd:sequence>

• Replace the conditionValue attributes with startsWith attributes and add a comma to the end of the attribute values.  This will allow the native schema processor to identify the start of master records and child records.  We also add a maxOccurs attribute to the elements modified so that they can have multiple instances in a sequence.

  • <xsd:element name="Item"     nxsd:conditionValue="L"> … </xsd:element>	<xsd:element name="Item"     nxsd:startsWith="L,"     maxOccurs="unbounded"> … </xsd:element>
    <xsd:element name="Room"     nxsd:conditionValue="P"> … </xsd:element>	<xsd:element name="Room"     nxsd:startsWith="P,"     maxOccurs="unbounded">     … </xsd:element>

• Add an <Items> element as a sequence to the <Room> element sequence and move the <Item> element to be inside the <Items> sequence.

  <xsd:element name="Room" nxsd:startsWith="P," maxOccurs="unbounded">
      <xsd:complexType>
          <xsd:sequence>
              …
              <xsd:element name="Items" maxOccurs="1">
                  <xsd:complexType>
                      <xsd:sequence>
                          <xsd:element name="Item" nxsd:startsWith="L," maxOccurs="unbounded">
                              …
                          </xsd:element>
                      </xsd:sequence>
                  </xsd:complexType>
              </xsd:element>
          </xsd:sequence>
      </xsd:complexType>
  </xsd:element>

This gives us a native schema format that looks like this:

Note that this is the structure that we were aiming for in the first place.

Sample Code

I have created a simple BPEL process that performs the following steps

• Read a laundry file using the wizard generated native schema format.  This creates an XML document with two distinct records types.
  • Note that in the process I do not delete the file so it is important to make sure that if you re-use the same file with the process you need to update its timestamp!
• Read the laundry file again using the modified native schema format.  This creates an XML document with master-detail style records which reflects the actual format of the file.
  • Note that I use a synch read with the filename provided by the inbound header from the previous file read.   I delete the input file after reading it.
• Write the laundry file using a pure XML schema to create an XML document file of the laundry list.

Sample code is zipped up as a JDeveloper project and can be downloaded here.  In addition to the normal BPEL artifacts within the project, I have included a sample laundry file (laundry.sample.txt) in the top level of the project directory.  After deploying to a BPEL server the process will look in C:\FileTransfer\InBound for the input file, after processing the input file it is written to C:\FileTransfer\Processed and the output file is generated in C:\FileTransfer\OutBound.  Either create appropriate directories or edit the project to use new directories.

Documentation

This entry has used the facilities of the native format schemas in SOA Suite.  These are documented in chapter 7 of the Oracle® Application Server Adapters for Files, FTP, Databases, and Enterprise Messaging User's Guide.

Good luck in using the adapters to process master-detail records!

One of Oracles chosen charities in the UK is the NSPCC, the National Society for the Prevention of Cruelty to Children.  The NSPCC is the UK's leading charity specialising in child protection and the prevention of cruelty to children. It is the only children's charity with statutory powers, enabling it to act to safeguard children.  In the UK it is well known for running Child Line, a 24-hour helpline for children in distress or danger. Trained volunteer counsellors comfort, advise and protect children and young people who may feel they have nowhere else to turn.

This year together with a number of other Oracle UK employees I will be participating in the Three Peaks Challenge in July - climbing to the top of Ben Nevis, Scafell Pike and Snowdon, all within 24 hours.

This will be no mean feat - it involves making your own sandwiches as well as walking for 15 hours/30 miles up/down over 10,000 feet interspersed with 500miles of driving. I've been walking up and down stairs in the office for weeks in preparation.

If you would like to sponsor me in this somewhat madcap activity, then donations can be made via PayPal, Credit or Debit Card at my Justgiving site.  If you’re a UK taxpayer, Justgiving makes sure 25% in Gift Aid, plus a 3% supplement, are added to your donation.

So go ahead, sponsor me!

I have just been with a customer who was using Oracle Enterprise Linux 5.  Now this shouldn’t be any different from other Linux installations except for one minor problem, the SOA Suite installer insists on checking that the Linux flavor is one explicitly supported by SOA Suite.  Well OEL wasn’t in the list when SOA Suite 10.1.3.1 came out and so the installer fails on the pre-requisite checks and won’t go any further, even if you applied all the required patches to the OS.  Fortunately there is a patch 6339508 which provides replacement pre-requisite tests.  To use it you need to add two parameters to the runInstaller command as shown below.

./runInstaller PREREQ_CONFIG_LOCATION=<PATCH_LOC>/prereq –paramFile <PATCH_LOC>/oraparam.ini

PATCH_LOC is the location where you unzipped the 6339508 patch.  With these new parameters the installer correctly recognizes Oracle Enterprise Linux as a supported platform.  Note that OEL needs some specific patches when used with SOA Suite and these need to be installed prior to running the installer.  Check the documentation for details.

I am seeing an increasing number of customers taking up OEL, I think because of the attraction of a single company supporting the whole technology infrastructure stack, OS, AS and DB.  I expect to see more of this still in the future.

Installing SOA Suite 10.1.3 with an 11g Database

Just at a customer who has an 11g RAC database that he wants to use for his SOA repository.  If you try and install SOA Suite into an 11g database, it tells you that the database is not supported and the irca configuration assistant fails to find a java library.  11g is a certified platform for SOA Suite 10.1.3.4 so here is how to get it installed.

IRCA

Before installing the SOA Suite executables you need to run the irca script to create the SOA Suite schemas in the 11g database.  The irca script needs to be able to find an ojdbc14.jar file.  This file is not shipped with the 11g database which provides libraries for Java 5 and Java 6 rather than the almost obsolete Java 1.4.  This leaves you with a couple of options;

• Use an Oracle 10g home as your Oracle home, if you have one on the machine, when running irca.
• Copy the JDBC libraries from an Oracle 10g home (<Oracle10g_Home>/jdbc/lib) to the Oracle 11g jdbc location (<Oracle11g_Home>/jdbc/lib).

Having done this then the irca script should run fine and create the ORABPEL, ORESB and ORAWSM schemas for you in an 11g database.  You are now ready to run the SOA Suite installer.

Installer

When you run the installer to create the SOA Suite instance it will fail when checking for the existence of the SOA Suite schemas unless you patch the installer files first.  The way to do this is to download patch 6265268 from MetaLink and follow the instructions which basically require you to modify the install media as follows:

• Replace DBConnectQueries.jar
  • Move
    • <MEDIA>/stage/Queries/DBConnectQueries/8.4/1/DBConnectQueries.jar
  • to
    • <MEDIA>/stage/Queries/DBConnectQueries/8.4/1/DBConnectQueries.jar.pre6265268
  • Copy
    • <PATCH>/DBConnectQueries.jar
  • from the patch to
  • <MEDIA>/stage/Queries/DBConnectQueries/8.4/1/DBConnectQueries.jar
  • Note that the current patch documentation incorrectly refers to an 8.5 directory rather than the 8.4 that actually exists.
• Replace IP_DBQueries.jar
  • Move
    • <MEDIA>/stage/Queries/IP_DBQueries/3.0/1/IP_DBQueries.jar
  • to
    • <MEDIA>/stage/Queries/IP_DBQueries/3.0/1/IP_DBQueries.jar.pre6265268
  • Copy
    • <PATCH>/IP_DBQueries.jar
  • from the patch to
    • <MEDIA>/stage/Queries/IP_DBQueries/3.0/1/IP_DBQueries.jar

You can now launch the installer and there will be no complaints about an 11g database.  Note that if you are installing a SOA Suite cluster then this will need to be done for each SOA Suite instance being installed.

What’s the Point?

As you are making these changes your mind keeps asking why you are doing this.  Apart from being told to do so by your DBAs there are some good reasons for using 11g.  The 11g database is the most manageable Oracle database ever, and several options only work on the 11g database.  11gR1 has been out for a long time now and so from a longevity perspective its best to put new deployments on an 11gR1 platform even if you have a release-1 strategy to avoid “bleeding edge” deployments.

Finally as you can see, it is not that hard to use an 11g database with SOA Suite.