The Importance of Guiding Principles

Whether speaking about enterprise architecture or design within a project, guiding principles are paramount to keeping your focus on what's important to guiding decisions.  Some examples of these would be software re-use over creation, and simplicity over flexibility to make things more maintainable.  It's important to establish what your guiding principles are prior to having multiple teams making decisions either based on uniform principles or using their own discretion.

This importance to me was illustrated clearly with a little-known rule in the NFL.  As a big NFL fan, you would expect with their use of instant replay and reviewing all scoring plays and turnovers, their guiding principle would be the correctness of ruling plays that directly affect the outcome of the game.  However, as reinforced by an ill-fated decision made recently by the coach of the Detroit, if you throw a challenge flag on one of these plays, it renders the play un-reviewable and your team gets penalized 15 yards.  I'm guessing the purpose of the rule is to ensure coaches don't try to become too demonstrative against the officials, but the end result is not getting the play called correctly in some cases.

Had they determined a guiding principle was to ensure plays are called accurately (e.g. accuracy over punishment), this rule would never have been ratified, which has now resulted in a situation the possibly changed the course of a game for a team.  Having a handful of these guiding principles, a small enough number that allows remembering them clearly across teams, will ensure your organization is uniformly making decisions that can impact projects going forward.

Using Spring Portlet MVC 3.0 in Oracle Webcenter Portal (Spaces)

You may find yourself in the same quandary as me.  I want to stand up a portal quickly at an Oracle shop(client), so Webcenter Portal is currently the defacto choice as the solution, and in this case Spaces has been chosen for its ease of setup and collaboration (including built-in integration with BPM).  However, the client is not an ADF development shop, but is familiar with another web development framework like Spring MVC. Since the only way to expose portlets in Webcenter Portal 11g is using WSRP (Web Services for Remote Portlets), it shouldn't really matter what framework you use to develop the portlet as long as it is deployed using WSRP you can register it with Webcenter Portal and use it as you desire.  Note that there are plenty of more informed blogs and websites that provide the argument whether to use Webcenter Portal: Framework vs. Webcenter Portal: Spaces, as well as whether to extend your portal using either WSRP Portlets or ADF task flows.  I will defer to those sites on providing you those decisions to make, but if you have selected WSRP Portlets, here's how you can use your favorite IDE to develop them and deploy them properly to Webcenter Portal: Spaces.  Doing the same with Framework would entail similar steps, you would need to create a WSRP connection to the portlet producer from within JDeveloper and add the portlet to your page through JDeveloper instead of the Spaces web application. As a quick overview, I tried determining how to WSRP enable my portlet for some time before I stumbled onto the documentation within Oracle's 11g docs describing how this can be done via script as a pre-deployment step for any JSR-286 compliant portlet.  This instruction is within the administrator's guide and not the developer's guide, which made me realize their intention of separation of roles for deployment.  So I will document how to get a portlet into Webcenter Portal in several steps based on role to be consistent with this intention:

1. Developer creates JSR-168/286 compliant portlet using their IDE and whatever framework they want
2. Developer packages portlet up as EAR file for deployment
3. Deployer updates EAR file using provided script to expose JSR-286 portlet as WSRP Portlet Producer EAR, and adds weblogic.xml to embedded WAR to specify shared library to include (otherwise deployment FAILS)
4. Deployer deploys WSRP .ear to Webcenter Portlet Producers server.
5. Webcenter Portal: Spaces Administrator registers WSRP v2 portlet producer in Webcenter Portlet: Spaces using WSDL URL.
6. Webcenter Portal: Spaces page designer adds portlet to desired page and sets any default configurations.

Oracle Webcenter Portal 11.1.1.6 VirtualBox: Installing Webcenter Portlet Producers

Overview

In order to integrate some existing web site content/functionality into your Webcenter Portal, you'll likely need to have the provided Portlet Producers Omniportlet and Web Clipping portlet installed in your Webcenter virtual machine.  These make integrating with existing sites much easier and quicker than a home-grown solution, but will need to be installed if you're using the Oracle VirtualBox VM that includes Webcenter Portal.

Prerequisites

First, you'll have to download the VirtualBox VM that runs Webcenter Portal from Oracle at http://www.oracle.com/technetwork/middleware/soasuite/learnmore/vmsoa-172279.html.

Second, you should have already installed it, and then started it up per the instructions at the site above.  In my case I have configured the "domain" wc_spaces, since I want to setup to use Webcenter Portal: Spaces locally.

Take a Backup/Snapshot of the VirtualBox Image

Of course nothing will go wrong, right?!?!  But just in case, make sure you at least snapshot your VM prior to following these steps.

Adding Webcenter Portal Portlet Producers

Since the virtual machine does not include the Omniportlet and Web Clipping portlet out of the box, you'll need to install these and integrate the new WC_Portlet server installed into the VMConfig application Oracle ships with the virtual machine.

Odd numeric issue with XSLT subtraction

On my project that automates a business process within Peoplesoft, we recently ran into an issue where we were updating a Component Interface with a number representing U.S. dollars and it complained about the length.

Upon investigation I could see that for some reason we were trying to insert the value 1.48999999997 into a field that only supports 2 digits past the decimal point, or a scale of 2. So this indicated to me 2 issues with our project:

1. The Java web service we wrote to call the Peoplesoft component interface did not handle erroneous data being sent in, and
2. Somewhere in our automation code before this we were creating a bad currency amount.

To solve the Java web service issue, I noticed our interface classes used both floats and doubles for the currency amounts. And since the Peoplesoft component interface classes required BigDecimals for all the amount fields, I figured the BigDecimal conversion was likely the issue. The code was converting these using the BigDecimal.valueOf(long) or BigDecimal.valueOf(double) methods. While stepping through a JUnit test case I wrote, I could see that the amount was not getting scaled or rounded at all, so we were writing 1.48999999997 into the field causing the error. After revisiting the javadocs for BigDecimal to refresh my memory, I could see we likely needed to simply call the setScale(scale, RoundingMethod) to ensure we didn't try to insert such values in the future. After the change I unit tested it again and could see that now we could handle all the various data values sent in and correctly scale and round the value accordingly.

The other issue was tracked down by my fellow developer to an XSLT that was doing a simple subtraction of 2 currency values, but for some reason was creating this strange value. In this test case the original numbers were similar to 2450-2448.51, which was resulting in 1.48999999997! I figured somehow this was related to the BigDecimal class as well, behind the scenes used by the XSL engine in OC4J (Xalan?). As a workaround, we multiplied the value by 100, rounded it using the XSLT round() function, then divided again by 100 to ensure the correct scale was applied. While ugly it at least functioned as expected.

Using DBMS_LOCK package to implement singleton pattern

One thing that is inevitable as you start replacing batch-oriented integration strategies with more real-time, transactional strategies like BPEL and ESB, especially in a clustered environment, is that you'll run into APIs and database procedures that worked fine in a batch mode, but in a multi-threaded real time integration start breaking.

Using BPEL's Custom Indexes for BPEL Console Searching

Recently I had a request to store unique identifiers (nothing in violation of SOX requirements, a custom number only recognized at this client) as one of the custom indices in BPEL so associated instances could be searched using the BPEL Console.

While this isn't a difficult thing, as the API is well-defined and easy to use within an embedded Java activity, I ran into some things that may save you some debugging time in the future, or myself when I search my own blog later to "remember" how I got it working as expected.

This blog posting will be short and sweet. The one caveat that I found was if you have either an XML-based or Message-based variable, be careful with the getVariableData function, as it will generally return an Oracle XMLElement object, so you'll need to get the text from it and not call the toString() function of it when setting the custom index. I've generally found it much easier to create a Simple-type variable of type String, then use a Copy operation with an Assign activity to get the value from within either an XML-based or Message-based variable into the simple String variable, then in the embedded Java it's easy to use getVariableData(variableName).toString() to set the custom index.

Publishing large XML docs from BPEL to an XMLType column

As is often the case, this was purely a trial-and-error experiment that I got working in a specific way, but there may be other ways as well. In other words, use these instructions at your own risk, as I assume no liability for any problems these may cause in your environment.