Java best practices

Saving files

Instead of relaying on the platform JVM, save your files on the OS encoding your files names using standard API

 java.net.URLEncoder.encode(String s, String enc)
 java.netURLDecoder.decode(String s, String enc)

Otherwise the results might be different from one OS to another.

JavaMail API

Before digging into the code, here are some basic concepts:

Interactions between email servers(software) and clients are governed by email protocols, the most common email protocols are:

• POP (aka POP3)
• IMAP (aka IMAP4)
• MAPI.
• SMTP

POP
POP version 3, allows email client software to retrieve email from a remote server. Its main characterist is that when the e-mails are seen, those are removed from the server and stored on the user's PC.
 
IMAP
Internet Message Access Protocol, on version 4, IMAP4, allows a local email client to access email messages that reside on a remote server.  The emails reside on the server and only are remove explicity by the user.

IMAP over SSL (IMAPS) uses port number 993.
 
MAPI 
Proprietary email protocol of Microsoft, that can be used by Outlook to communicate with Microsoft Exchange (its email server software).
 
SMPT
Its the only protocol to send emails, POP and IMAP are used to incoming emails and SMTP is for outgoing messages. It is also known as SMTP/MIME.


JavaMail Layered Architecture

In few words, JavaMail API only defines the interfaces, and depending on the protocol, and implementation is required, this is very similar to JDBC and the specific database drivers.

Abstract Layer: declares classes, interfaces and abstract methods intended to support mail handling functions that all mail systems support.

Internet implementation layer: implements part of the abstract layer using internet standards, the service providers  implement the JavaMail API (for each required protocol POP3, SMTP, IMAP)

JavaMail Framework is used for

1. Create a mail message consisting of a collection of header attributes and a block of data.Create a Session object, which authenticates the user, and controls access to the message store and transport.
2. Send the message to its recipient list.
3. Retrieve a message from a message store.

Main Classes

javax.mail.Session 
Require it to get a mail session, you connect to the mail server 

javax.mail.Message
The Message class is an abstract class that defines a set of attributes and a content for a mail message.
It also implements the Part interface, which defines attributes that are required to define and format data content carried by a Message object, and to interface successfully to a mail system.

You send a new message by instantiating an appropriate Message subclass and then you set the attributes such as recipient address, subject, and inserts the content into the Message object.

A Message object can contain multiple parts, where each part contains its own set of attributes and content. The content of a multipart message is a Multipart object that contains BodyPart objects representing each individual Part.

javax.mail.Folder
Messages are stored in Folder objects. A Folder object can contain subfolders as well as messages, thus providing a tree-like folder hierarchy. With this you fetch, append, copy and delete messages.



javax.mail.Transport
Require it to send a message(email) via this class/method send()


References:

• MIME

Understanding JAAS

In order to understand JAAS, the following concepts are required:

1. LoginContext


2. LoginModule


3. Callbackhandler


4. Subject


5. Principal


6. Credentials

All the above concepts are implemented with the following an web application example to be explained here.

This is a simple application that has a login form waiting for username & password. At the time the user submits the form, a servlet is listening for that action. Once the servlet gets the user data it calls the LoginContext asking for an specific LoginModule list to be called. Each LoginModule is executed and validates the user account. At the end, only if all Login Modules succeded, the complete process succedes, otherwise the application displays that the account is not valid.

The important thing here to understand is that each Login Module implementation can be changed, but the structure remains.

Please see the below example to have a general understanding of JAAS.

The whole project can be downloaded from:

svn checkout https://jsf-tutorial-desperatedevs.googlecode.com/svn/branches/command-line-demo

Spring & iBatis

Steps to configure Spring and iBatis

For each step create the artifact

1. Database object, in this example a single table is used with MySQL.
2. SqlMap.xml that describes your SQL mapping.
3. SqlMapConfig.xml pointing to your SqlMap.xml.
4. Bean that will hold the data from the table
5. DAO interface
6. DAO implementation
7. applicationContext.xml and configure your DAOs.
8. Testing

Download the code from: svn checkout https://mybrain.googlecode.com/svn/branches/mybrain

Correlation with BPEL

An application must maintain data integrity when messages are exchanged between services. A manufacturer that receives orders, for example, must not mix data for one order with the data for another.

A BPEL process addresses this issue with correlation sets, each of which is a list of properties whose values are expected to remain constant throughout a process or throughout a specific scope, even as data is transmitted to and from partner services.

For purposes of an example, here is a process that records the purchase orders of custumers, so it needs to identify each specific custumer-order. This is the diagram of the whole process:

The following steps describe how to identify a process using correlation sets:

1. First, the following namespace into your WSDL file:
             xmlns:bpws="http://docs.oasis-open.org/wsbpel/2.0/varprop"
   
   
2. Create the property to be used to identify your process. In this example we will use 2 values to identify the process or the PO of the customer, so add the following at the end of your WSDL.
                   <bpws:property name="customerID" type="p:string" />
                   <bpws:property name="orderNumber" type="p:string" />
   
   
3. The process will start after answer the first request, for example, when the customer puts a new Purchase Order, the process will return the PO number, then the BPEL process will identify an specific process using the CustomerID and the OrderNumer. To do the previous logic, add the following to your WSDL. This is telling that the CID and Order will be used as a combined key.
   
               <!-- sendResponse -->
               <bpws:propertyAlias propertyName="tns:customerID" messageType="tns:sendPOResponse" part="confirmation">
                   <bpws:query><![CDATA[/tns:CID]]></bpws:query>
               </bpws:propertyAlias>
               <bpws:propertyAlias propertyName="tns:orderNumber" messageType="tns:sendPOResponse" part="confirmation">
                       <bpws:query><![CDATA[/tns:Order]]></bpws:query>
               </bpws:propertyAlias>
   
   
4. Also, for each subsequent message sent to the BPEL process we will require that the user sends the CID and Order, to do that, define that while requesting a operation those values must be sent. Example:
               <!-- QUERY Request -->
               <bpws:propertyAlias propertyName="tns:customerID" messageType="tns:queryPORequest" part="query">
                   <bpws:query><![CDATA[/tns:CID]]></bpws:query>
               </bpws:propertyAlias>
               <bpws:propertyAlias propertyName="tns:orderNumber" messageType="tns:queryPORequest" part="query">
                   <bpws:query><![CDATA[/tns:Order]]></bpws:query>
               </bpws:propertyAlias>
   
   
5. Now, define the correlationSets into your BPEL process
              <bpws:correlationSets>
                   <bpws:correlationSet name="PurchaseOrder" properties="tns:customerID tns:orderNumber"/>
               </bpws:correlationSets>
   
   
6. As previously mentioned, the process will start when answering to the first request, so we define that inside the first reply activity:
               <bpws:reply name="replyOutput" operation="sendPO" partnerLink="POLink" portType="tns:purchaseOrderProcess" variable="output">
                   <bpws:correlations>
                       <bpws:correlation initiate="yes" set="PurchaseOrder"/>
                   </bpws:correlations>
               </bpws:reply>
      
   
7. And in subsequent requests, the correlation only will be used, not initiated again. For example, while querying the process:

           <bpws:onMessage operation="queryPO" partnerLink="POLink" portType="tns:purchaseOrderProcess" variable="queryInput">
               <bpws:correlations>
                        <bpws:correlation initiate="no" set="PurchaseOrder"/>
                </bpws:correlations>




Download the example from here.

Consuming external web services

Example of how to call an external Web Service from a BPEL process:

Follow these steps:

1. First, download and install "HelloWorld" Web Service into your servlet container. This simple service has 2 operations:
   1. sum: returns the result of adding two numbers. This is the operation we will use.
      
   2. example: concatenates your input with "External WebService".
2. Before calling this WS check if the web service is working fine. Test the "sum" operation.
3. Open your Eclipse and create a new BPEL project. Name it as "HelloCaller".
4. Create a new BPEL process file with the following data:
   1. BPEL Process name: helloCaller
   2. Namespace: http://mydomain.org/bpel/helloCaller
   3. Template: Synchronous BPEL process
5. Add the HelloWorld WSDL file into the process. Be sure your file is visible to your project.
   
   
   
   
   
6. Add a Partner Link and named it as "helloLnk".
7. Open the details of "helloLnk" and click on "Browse" button. Then a dialog will appear, at the bottom click over the "Add WSDL" button. Select the HelloWorld WSDL file.
8. Select the port named as "HelloWorldServicePortType"and click "OK" button; a new dialog will appear.
   
   1. Define the name of your Partner Link Type as "helloPLType" and click "Next" button.
      
   2. Type a Role Name as "helloProvider" and click "Finish" button.
      
9. Bellow the "Partner Role" section select "helloProvider".
   
   
   
   
   
10. Open the BPEL process (helloCaller.bpel) with the BPEL designer and add the following activities and name them as suggested:
    1. Assign: InitializeVars
    2. Invoke: SumNumbers
    3. Assign: SetResult
    
    You should see your diagram as the following:
    
    
    
    
    
    
11. Open the properties of "SumNumbers" and select the "sum" operation from the "HelloWorldPortType".
    
    
    
    
    
    
    
    
    
    
    
    
12. Open the properties of "InitializeVars" activity and add a copy step.
    From: Fixed Value
    
    <ns0:sum xmlns:ns0=http://webservice.augusto.org>
    <ns0:in0/>
    <ns0:in1/>
    </ns0:sum>
    
    
    To: Variable
    Select helloLnkRequest the "and then "parameters"
    
    
    
    
13. Add a new copy step to "InitializeVar" with the following data:
    
    
    
    
    
14. And add the last copy step to the "InitializeVars"
    
    
    
15. Now, select the "SetResult" and add 2 steps. In the first one initialize the response:
    1. From: Fixed Value
       
       <tns:helloCallerResponse xmlns:tns="http://mydomain.org/bpel/helloCaller">
       <tns:result/>
       </tns:helloCallerResponse>
    2. To: Variable
    3. Select output the and then "payload"
16. Finally, copy the result from the "HelloWorld" service to the output of your BPEL process.
17. You need to define the service and the location of it.
18. Define the deployment descriptor. Remember that for every partner link used with a <receive> activity must be matched with a <provide> element, and every partnerLink used in an <invoke> activity must be matched with an <invoke> element in deploy.xml. For example, for this process the following code is used:
    

<process name="pns:helloCaller">
<active>true</active>
<provide partnerLink="client">
<service name="pns:helloCallerService" port="helloCallerPort" />
</provide>
<!-- Hello World Web Service -->
<invoke partnerLink="helloLnk">
<service name="wns:HelloWorldService" port="HelloWorldServiceHttpPort" />
</invoke>
</process>

1. Now, deploy your helloCaller service and test it. Download the example from here.
   

Software required to run the example:

1. Eclipse
2. BPEL designer for Eclipse - http://www.eclipse.org/bpel/
3. Apache ODE 1.3.2

References

1. How to create a Partner Link
   

BPEL fault handling

Faults in BPEL can arise in various situations:

1. When a BPEL process invokes a synchronous web service operation, the operation might return a WSDL fault message, which results in a BPEL fault.
2. A BPEL process can explicitly signal (throw) a fault.
3. A fault can be thrown automatically, for example, selectionFailure or uninitializedVariable; these typically indicate a problem in your process where you've not implemented something correctly.
4. The BPEL server might encounter error conditions in the run-time environment, network communications, or any other such reason. This kind of faults are called "Failures".

Here is an example of how to catch and access WSDL faults thrown by an External Web Service. This is the scenario:

1. You have an external web service named "fault". This WS generates a fault because something in it fails.
2. Then, you have a BPEL process named "faultCaller" that calls the "fault" service, so you must catch the fault thrown.
3. Also, if a network failure appears while calling the "fault" service, then your BPEL process should handle that error.

Let's create the scenario, first the "fault" service

1. Declare a fault message:
   

   
   <element name=" MyFault">
    <complexType>
     <sequence>
      <element name="myError" type="string"></element>
           </sequence>
        </complexType>
   </element>
   
   
   <message name="FaultMessage">
       <part name=" payload" element="tns:MyFault"></part>
    </message>
   
   
   <operation name="process">
    <input  message="tns:FaultHRequestMessage"/>
       <output message="tns:FaultHResponseMessage"/>
       <fault name=" fault"message=" tns:FaultMessage"></fault>
   </operation>
   

   
   
2. Then, inside your BPEL process throw an arbitrary fault:
   
   

   
   < bpws:throw faultName=" someFault"/>
   

3. Finally, build your fault message:
   
   

   
   <bpws:from>
       <bpws:literal>Error from External WebService </bpws:literal>
    </bpws:from>
     <bpws:to part=" payload" variable=" myFault">
       <bpws:query queryLanguage=" urn:oasis:names:tc:wsbpel:2.0:sublang:xpath1.0"> <![CDATA[/tns:myError ]]> </bpws:query>
     </bpws:to>
   

   
   
4. Deploy it as
   
   

   <soap:address location=" http://localhost:8080/ode/processes/fault">

   
   

Now, create "faultCaller" service

1. First, add the namespace for the failure handling.
   

   
   < xmlns:ext="http://ode.apache.org/activityRecovery">



2. Declare the variable that will hold the error comming from the "fault" service.
   

   <bpws:variable messageType=" ns0:FaultMessage" name=" faultMaker" />

   
   


3. Inside the invoke activity that calls the "fault" service put the fault handling activities. First lets put the failureHandling structure.
   
   

     <ext:failureHandling>
                 <ext:faultOnFailure>true</ext:faultOnFailure>
                 <ext:retryFor>2</ext:retryFor>
                 <ext:retryDelay>30</ext:retryDelay>
           </ext:failureHandling>

   
   
4. Now, Catch run-time environment faults, like network communications issues:
   

   <bpws:catch faultName="ext:activityFailure" >
               activity
             </bpws:catch>
   

   
   
   


5. And finally, catch your own faults comming from the "fault" service.
   

   <bpws:catch faultName="ns0:fault" faultVariable="faultMaker" faultMessageType="ns0:FaultMessage">
               activity
           </bpws:catch>

   
   
   
   
6. Your BPEL process should be like the following diagram:

While calling "faultCaller", you should catch your fault message error comming from "fault" service, and if you undeploy the "fault" service, then if you call again the "faultCaller" you should catch the failure.

Download the whole example from here.