Friday Dec 19, 2008

Jumpin' on the Fuji Bandwagon

It's here!  SchedulerBC now works with Fuji and IFL (but the binaries aren't completely part of the next Fuji M4 milestone release yet, so you'll have to get them from here)!  The following instructions show how to run SchedulerBC in NB 6.1 using IFL.  Skip any steps, of course, that you have already done:

  1. Install JDK 1.6 from here and enusre that JAVA_HOME environment variable points there
  2. Install Apache Maven 2.0.9 from here by:
    • Unpacking into folder of your choice
    • Setting environment variables MAVEN_HOME=...\\apache-maven-2.0.9 and MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=256m
    • Ensuring you're using a fresh Maven repository by pointing the <localRepository> element to it in the {user home directory}\\.m2\\settings.xml file (for example on Windows C:\\Documents and Settings\\username\\.m2\\settings.xml)
  3. Install NetBeans 6.1 IDE with Patch 4 available from either the GlassFish ESB or OpenESB Installer (latter has problems when mapping with NM Properties so use GlassFish ESB until further notice) available here
  4. Install Maven2 3.1.5 NBM Plugin from the NetBeans Update Center

  5. Go to Tools | Options | Miscellaneous | Maven 2 and direct NetBeans to always use the external Maven for building projects

    and that Local Repository field is set to the chosen Maven repository mentioned above.
  6. Install NetBeans IFL Support Plugin available here
  7. Install NetBeans Fuji Server Plugin available here
  8. Go to Tools | Options | Miscellaneous | Fuji and set Fuji Archetypes Version to 1.0-M4-SNAPSHOT:

  9. Install the Scheduler Archetype (download here) into pertinent Maven repository:

  10. Delete the .index directory in the Maven repository to ensure the newer Scheduler Archetype is used when the repository is next indexed
  11. Install pre-release Fuji Milestone 4 from fujifelix-1.0-M4.jar by extracting to a directory of your choice
  12. Add a new Fuji Server by going to Services window (tab) clicking on the Fuji Servers node and Add Server. Set both Root Directory and Working Directory to the directory where fujifelix-1.0-M4.jar was extracted.  Afterwards, right-click Start to start the new Fuji Server node.
  13. The remaining instructions creates and runs a simple Fuji Integration Application project:

  14. Create a new Maven project (without existing POM):

  15. Select the Fuji Integration Application Archetype:

  16. Enter the desired project Project Name, Project Location, and Group Id:

  17. HINT, you MUST be connected to the internet before you press Finish to create the project because there are lots of artifacts that need to be downloaded from all sorts of Maven repositories on the net.

    KNOWN ISSUE, the first time you create a Fuji Integration Application Archetype project, the project will be named <Badly formed Maven project>.  Don't despair, this will rectify itself once the first IFL file has been defined and Generate Service Artifacts done.

  18. Open the IFL Files node and edit the pre-created app.ifl IFL (Integration Flow Language) file and type in the IFL as shown below:

  19. Save the file and click on the green arrowhead button in the IFL editor toolbar (shown in above screenshot) to generate service artifacts for the project; this is how you configure the Binding services such as scheduler and file
  20. Next, configure the binding services by expanding the Service Config Files node as shown below and editing the respective files.  They typically are ready to run as-is, unless you want to customize their behavior.

    For File service:

    For Scheduler service, we're going to use the new hybrid so comment out the default simple section and uncomment the hybrid:

  21. For this demo, we do need to modify the File binding so that the output file is appended to:

  22. Select Clean and Build for the project:

  23. Select Deploy... for the project; not Run:

  24. Almost now have to start the deployed service assembly in the Services window (tab) under the Fuji Servers | Fuji M4 SNAPSHOT Server | Service Assemblies | SchedulerF4Demo node (path appropriately adjusted per your choices):

Congratulations!   You should now see in the output file specified for the file service:

Friday Dec 05, 2008

Systemic Qualities Enhancements

To make it even more useful, some essential Systemic Qualities have been added to Scheduler BC

  • Application Configuration

    You may have noticed a small icon (looks like an Application icon with a gear cog in it) affixed to the left of some labels in Scheduler trigger definition panel:

    As the tool tip indicates, these parameters are part of the available Application Configuration for the Scheduler Binding Component, and can be optionally configured at deployment time.  This is essential for Administrators in order to deploy a project, after Development and Quality Assurance have finished their tasks in the project lifecycle, since the run-time environment(s) that may be quite different in terms of locale.

    • To start, you need to associate a Configuration Extension profile with the respective Scheduler endpoint by clicking on the consumer icon of the Scheduler port in the CASA editor and selecting Properties:

    • Now, enter the desired name of the profile, such as the name given to the Scheduler WSDL (binding):

    • Next under the Services tab, make sure the GlassFish V2 Server and Scheduler Binding Component (sun-scheduler-binding) have been started, then right-click sun-scheduler-binding and select Properties:

    • Then, click Add button to add a new row representing all the Application configurable parameters for the Scheduler BC, using the same name for the Application Configuration Name as given in the CASA editor.

      Pay particular attention to values given for the startDate and endDate; they need to either be the string literals now and never respectively or, dates conforming to the format specified in Date Format of the GUI editor when the Scheduler WSDL (binding) was first created or subsequently edited.

    Now when the Composite Application is deployed, the Scheduler BC will use those Application Configuration that have been defined for the respective endpoint.

    Besides using NetBeans IDE to specify Application Configuration, you can also use:

  • Application Variables

    The message sent when a trigger is fired can now reference Application Variables that are set at deployment time and will be evaluated each and everytime prior to the message being sent; this allows the variables to be changed dynamically.  This feature is useful if the message sent contains confidential information such as passwords that firstly, you don't want to reveal statically in the message while it's being configured in either the Simple or Cron trigger editor.  Secondly, passwords used in enterprises often require periodic maintenance for security reasons and thus the runtime administrators need access to these, without touching the business logic specified during design time and verified during quality assurance.  To utilize Application Variables:

    • Reference them in the Message field of the trigger editor, using the dollar sign curly braces format (highlighted in following figure):

      Note, any Application Variable defined is available to all JBI applications deployed in a GlassFish server and thus care needs to be taken to qualify these for different deployments, typically by prefixing their names with a unique key such as the name of the WSDL binding ("cronBinding." as shown here.

    • Next, prior to deployment time, set the referenced Application Variables by right-clicking the GlassFish V2|JBI|Binding Components|sun-scheduler-binding node in the Services tab, select Properties and click on the ellipsis ("...") button for the Application Variables property in the Configuration section. Press the Add button and choose the type of variable desired, such as a Password type:

    • For each Application Variable, enter the Name exactly as referenced in the Message field, of course omitting the dollar sign and curly braces, and the corresponding value (note, Password fields are masked out for confidentiality); the latter cannot reference another Application Variable.

      Press OK when done and the Application Variables are ready for use by the deployment:

    • Like Application Configuration, Application Variables can also be configured using the Sun Java System Application Server (GlassFish) Admin Console:

    • Similarly, there are asadmin CLI commands to create (create-jbi-application-variable), update (update-jbi-application-variable, and delete (delete-jbi-application-variable) Application Variables.

    Here's the output using the configured Application Variables:

  • Logging

    Scheduler BC now emits more detailed and controllable logging.  Each log entry starts with an ID SCHEDBC-Xyyy where X is a digit that represent 7 different logging levels: 1 (FINEST), 2 (FINER), 3 (FINE), 4 (CONFIG), 5 (INFO), 6 (WARNING), and 7 (SEVERE) that are explained here.  Note, levels 1 through 3 inclusive are not internationalized as they represent debugging levels.

    Here's a sample output:

Friday Oct 17, 2008

Scheduler Redux

The surgery was successful and the patient has become a BC!  Anyhow, Scheduler BC works pretty much the same as any other, such as File BC.  However, with the recent WSDL Binding Wizard changes across the board for all BC's,  it's worth mentioning how to create a deployment for a Scheduler BC triggering a BPEL to write to a File BC.

Create a Scheduler WSDL Document

  • Launch the WSDL Binding Wizard by right-clicking over the Process Files folder of a BPEL project and select New | WSDL Document

    • Or equivalently, select New | Other | ESB (Category) | Binding (File Type) from the Process Files context menu

  • Enter an appropriate File Name for the WSDL, choose Concrete WSDL Document for the WSDL Type, select SCHEDULER from the Binding drop-down box and press Next
  • Press the Add button to add a new Trigger, key in appropriate data and press Add Trigger button when done

  • Optionally, define a custom date and time format to be used with the scheduler; this format is used both to interpret date and time values persisted in the Scheduler's WSDL as well as displaying the date and time in the message sent to the endpoint being triggered

  • Compose the Format by selecting from the various date/time component Pattern drop-down boxes, as well as typing other literals; all the while a Sample text field illustrates what the date and time will look like

  • Press Finish and the new Scheduler WSDL editor appears

Create a File WSDL Document

  • Similarly, right click over the Process Files folder again, select New | WSDL Document and this time create a FILE Binding Concrete WSDL Document, of Type Write and press Next

  • Specify the respective fields and click Finish

Create a BPEL and Connect the Components
  • Create a new BPEL in the same Process Files folder and drag and drop the Scheduler WSDL to approximately the middle of the Ports column left of the BPEL canvas

  • OK the ensuing dialog confirming creation of Partner Link to represent the Scheduler BC consuming endpoint

  • Similarly, drag and drop the File WSDL to the right column

  • In the ensuing dialog, click the Swap Roles button since this time the BPEL is the consumer of the service the File BC provides

  • Create Receive, Assign, and Invoke activities in the BPEL and Edit the Receive activity to select the Partner Link representing the Scheduler BC

  • Press the Create button to create an Input Variable for the Scheduler operation by accepting all the default values in the pop-up dialog (not shown) and hit OK here

  • Similarly edit the Invoke activity and also create an Input Variable for the File BC operation

  • Double click on the Assign activity and map from the payload of the Scheduler input variable to part1 of the File input variable, and Save All your work

Deploy a Composite Application for Scheduler BC » BPEL » File BC

  • Create a new Composite Application project and drag and drop the BPEL project onto the CASA Editor canvas

  • Hit the Build (hammer) button twice (second time to get rid of progress label...known issue)

  • Right click over the CASA project and select Deploy (you must have a running Glass Fish server with Scheduler Binding Component installed already of course) and you should be getting results in C:\\temp\\output.xml like this:

Installation Binaries

  • You'll need to run the latest OpenESB or GlassFish ESB Installer for the desired platform from here (as of 24 October 2008) and it will have both design-time and run-time Scheduler BC components pre-installed.
  • Otherwise, a-la-carte binaries are available for:
    • Scheduler WSDL Binding Extension NetBeans plug-in (you may need to rename it back to a .nbm extension after downloading)
    • Scheduler BC GF plug-in

Wednesday Sep 17, 2008

Date/Time configuration enhancements added

Since my last blog about the  OJC Scheduler editor, the date/time specifications for the Simple Trigger's Active Period have been improved.  Also, there's now a SimpleDateFormat chooser GUI to specify formats.  Here's what the Simple Trigger panel looks like now:

The Now/Never checkboxes are mutually exclusive with their adjacent spinner (JSpinner) fields.  To enter a specific date, make sure the respective checkbox is unchecked and place the cursor in date/time component field that you wish to vary (for example, the 2-digit month in the screenshot below) and press either the up or down arrow in the spinner.

If you wish to change the date/time format, press the Format button and a SimpleDateFormat Chooser pops up:

Build the format by selecting a pattern from one or more of the Patterns drop-down boxes and the corresponding SimpleDateFormat pattern will be inserted at the current caret position in the Format field.  As you build, the Sample textfield reflects what the date/time will look like.  Similarly, you can now also easily configure the format of the Job Date Format field by choosing <define custom...> in the drop-down list and the same SimpleDateFormat Chooser will appear:

Incidentally, management has decided the Scheduler component should now be a Binding Component instead of a Service Engine, so this enhancement will be the last as for as the Scheduler in SE form is concerned.  It will take a little while before a BC version will be available.

Tuesday Sep 09, 2008

Announcing Scheduler Service Engine

Ever wanted to kick off your BPEL to do something like send a loan approval status to a customer every so often?  Now you can easily do so in OpenESB with the advent of the Scheduler (powered by OpenSymphony Quartz) Service Engine (SE)!  With a few simple steps, you can create schedule files that will trigger your BPEL provider endpoint with a message and begin a new Business Process instance that subsequently performs some task like sending status to loan applicants.  The following instructions assume you have some familiarity with how to use components in OpenESB, but if not please click here to get more acquainted.

  1. Create a new Scheduler project in NetBeans by going to File | New Project and choosing SOA category and Scheduler Module project type and then selecting Next:
  2. Enter an apropos name for the Scheduler project and select Finish:
  3. Create a schedule file that can contain one or more triggers by right-clicking in the Process Files folder of the newly created Scheduler project and selecting New | Schedule File menu item:
  4. Enter a meaningful name for the schedule file (the project and schedule file names form the prefix to the name of the Scheduler SE consumer endpoint—in this example, it will be schedLoansRUs-sendLoanStatusPort—that will be sending a message to your BPEL provider endpoint) and press Finish:
  5. A Table view editor for the schedule file appears and now simply click on the Simple Trigger toolbar button (just a clock) to create a new trigger (currently only Quartz SimpleTrigger has been implemented; CronTrigger will follow soon).  You can double-click in the Name cell to give the trigger a more meaningful name, as well as provide a Description:
  6. or if you're a diehard  XML fan, there's the XML Source view:

  7. With the respective trigger table row highlighted (note, the Selected checkbox is used for indicating selected triggers for deletion), you can specify the various parameters for that trigger.  Changes to a field are registered when either focus is lost or an Enter key is pressed (except for the Message text area since it will accept newlines as part of the data):
    • The Starting and Ending Date & Time entries delineate when this trigger will be active.  Until a date/time chooser is implemented (very soon; or please donate if you have a good free open-source one), you'll need to enter one manually in the default locale format (Java SimpleDateFormat is used); the first item in the Job Date Format exemplifies the default locale format.  Alternatively, if you want the trigger to be active immediately after the Composite Application has been deployed, choose Now and similarly select Never if the active period has no end.
    • A simple trigger basically repeats after a certain time interval so specify the Repeat Count or Indefinite and the various time units that comprise the overall time interval.
    • Finally, the Job section pertains to the Message that will be sent when the trigger fires and will contain a metadata part that details the appointed date and time the trigger was configured to fire (note, this may precede the actual time the message is received due to network latency) in the specified Date Format.  Moreover, the metadata will also contain the trigger's name and group to which it belongs.
  8. Save your work and right-click over the Scheduler project and select Build Project to generate the corresponding abstract WSDL file for the schedule:
  9. The abstract WSDL can be used to define a BPEL service to receive the trigger message and so we'll now go to File | New Project and select the SOA category, BPEL Module project type and press Next:
  10. Key in an apropos name for the BPEL project and press Finish:
  11. We need to copy and paste the abstract WSDL generated for the schedule from the Scheduler project into the BPEL project's Process Files folder (XML catalog referencing will be supported soon):
  12. To simulate sending a loan application status to a customer, we're just going to write to a file on disk.  Thus, we need to create a concrete WSDL for the File Binding Component (BC) and start by right-clicking the BPEL project's Process Files and selecting New | WSDL Document:
  13. Supply a meaningful name for the WSDL file and press Next (don't press Finish yet):
  14. Choose a One-Way Operation for the Operation Type and press Next:
  15. Then choose FILE Binding Type and now at last, press Finish:
  16. We're almost there and now have to define the BPEL process that is to be triggered by the schedule.  Right-click the BPEL project's Process Files folder and select New | BPEL Process:
  17. In the ensuing BPEL editor, drag and drop the Scheduler's abstract WSDL from the BPEL's Process Files folder to somewhere approximately the middle of the left gray column until you select a hotspot target dot:
  18. Now do analogously for the File concrete WSDL but to the right gray column:
  19. Next, drag and drop these activities from the BPEL Palette onto the canvas area at appropriate hotspot locations: a Receive, an Assign, and an Invoke:
  20. Select the edit icon (one with a pencil) of the Receive activity and specify the appropriate fields as illustrated below, remembering to create an Input Variable:
  21. Similarly, edit the Invoke activity and specify the fields as illustrated below, again remembering to create an Input Variable:
  22. Now double-click on the Assign activity to configure the Mapper for it, to do something similar to the following (note the use of the message metadata):
  23. "Are we there yet, are we there yet?"  Yup, almost.  We just need to dump both projects into a Composite Application project, build and deploy.  Thus, go to File | New Project and select SOA category, Composite Application project type and press Next:
  24. As always, enter a meaningful name for the Composite App and press Finish:
  25. Drag and drop both Scheduler and BPEL projects onto the Comp App editor canvas and press the Build (hammer) toolbar button (might need to press the Build button again to dismiss the Reloading progress meter):
  26. Connect the Scheduler consumer endpoint chevron to the BPEL provider endpoint (this will be enhanced soon to be automatically done); when there are multiple schedules defined and hence multiple scheduler consumer endpoints, it's prudent to choose meaningful names for the Scheduler project and schedule file because together, they help form the endpoint names as seen here:
  27. Save all your work and we're almost ready for deployment.  But first we must verify that the GlassFish Application Server and Scheduler SE are up and running by going to the Services window (tab):
  28. Alas, go back to the Projects tab and right-click the Composite App project and select Deploy:
  29. The Comp App project will start running and you should see a test.xml file in your OS temp directory (ex. C:\\temp on Windows) with content something like this (hint, you'll need to configure the File BC to use append mode):

  30. Voilà, you're done!  Happy trails!
  31. P.S. If you want to take a test drive, click here for the OpenESB installer and here for this Scheduler demo projects.


Edward Wong


« June 2016