SOPERA Blog

Publish Documentation without Proprietary DTP Software

The DITA Open Toolkit, can create and transform DITA XML files into various useful, readable text formats. It’s been around for a while, but as you may know, it’s a lot of work to customize and efficiently use this toolkit. We’d like to announce our customized version of the toolkit: the SOPERA DITA Framework for processing and publishing user documentation. It’s a really nifty little framework that generates neat PDFs, Eclipse Helps, and HTML files from DITA maps and topic files without recourse to any commercial, proprietary DTP software applications. That’s right, for free!

Try it, Test it and Send us Feedback

Go ahead and try it out if you want to by checking it out of googlecode from here: sopera-dita-framework. Before you start, please do read the readme.txt file and the accompanying project wiki pages. Granted the content is sparse but we’ve busy been trying, testing and playing with our framework so that we’ve fallen behind in documenting its usage and utility but we’re working on it. We’d also appreciate your feedback.

Anne Aloysious Development DITA, DITA OT, dita topics, ditamaps, Proprietary DTP Software, User Documentation

Updated SOPERA SOA Tutorial

If you’ve been following our blog posts, you’ll have read the Helios is Out post, dated 28th June 2010. We mentioned in that blog post to all users that in order to access the tutorial all you had to was simply download the Eclipse SOA package and from the Eclipse IDE GUI menu, select Help > SOA > Install New Tutorials. For those of you who did download and install it, we mentioned in the Eclipse Help, SOPERA SOA Tutorial: Rent a Car Example (accessible via the Eclipse Help in the IDE) that we’d be collecting your feedback in order to improve the quality of the tutorial. We’ve done the following:

• Tested the use case scenario in the tutorial
• Streamlined the content
• Added screencasts

Installing the Updated SOPERA SOA Tutorial

To install the tutorial, uninstall the existing version and install the update, start the Eclipse IDE:

1. Click Help > About Eclipse > Installation Details.
2. From the ensuing list, select SOPERA SOA Tutorial: Rent a Car (OSGi) and click the uninstall button.
3. Next, click Help > SOA > Install New Tutorials. This opens a new window: SOPERA SOA Tutorial Discovery.
4. In the SOA Tutorial Discovery window, check the option SOPERA SOA Tutorial: Rent a Car (OSGi) and click Finish.

You’re all set! We hope you enjoy the tutorial. Please send us your feedback via the SOPERA Forum.

Anne Aloysious Development

SOPERA Support for EDI and EDIFACT

Recently, we’ve discovered - thanks to a number of customer requests - that support for EDI and EDIFACT is a must-have feature. Currently, with our SOPERA DI we are delivering the first version of our EDI/EDIFACT related components, based on an open source smooks framework. These components work quite well for simple EDI messages. You can configure the EDI mapping and read EDI messages into your SOPERA DI Jobs. We have already used them in a few customer cases and have learned quite a lot from it. Here are some of the major issues we encountered:

• You need to specify the mappings manually, even when processing standard EDI messages, for example, UN EDIFACT.
• It’s hard to read the UN/EDIFACT interchange that contains multiple messages of the same type, and it’s impossible to read UN/EDIFACT interchange with multiple messages of different type.
• The current state of components is not capable of writing out EDI files, only parsing/reading is supported to date.
• The tooling provided to read EDI messages inside the SOPERA DI needs to be improved. For example, we could display the message structure to simplify the mapping with a point-and-click feature.

At the same time the framework we were previously using for parsing EDI messages in SOPERA DI EDI components has made significant progress in the areas mentioned above allowing us now to take advantage of these improvements as well as to continue with our efforts to test and fix bugs. Here I would like to give you a short preview of the improvements we’ve made in this area.

UN/EDIFACT Mappings

The first area we improved is the manual definition of EDIFACT mapping files. This task can be quite tedious - one has to convert the UN/EDIFACT definitions into an XML-based mapping that can be used for EDI parsing. With the updated EDIFACT tooling you can get them automatically generated from UN definitions. Let us take for example the UN Customs cargo report message (CUSCAR). The picture below demonstrates this process:

Automated Mapping Generation

Here we take the CUSCAR definition which is available for download for example from within the package d99a.zip, and automatically generate XML Mappings according to the CUSCAR description from the UN. Now you can be sure all segments, segment groups, fields, and components are available in the mapping with all cardinalities as well as optional and mandatory flags. Moreover, since the ZIP file from the UN contains not only a single CUSCAR dialect definition but many others you will also get them packaged and ready to use.

UN/EDIFACT Inter-exchange processing

As you might know the EDI inter-exchange may contain multiple EDI messages of different types, each messages starts with the header segment that defines the message type (dialect), release year etc. For example, here is the header for the CUSCAR message:

UNB+UNOA:2+SENDER+SENDER+100421:0437+1918'
UNH+163477+CUSCAR:D:99A:UN:SCPRBL'

The second field of the UNH segment defines the dialect - here it’s CUSCAR released in the first part of the year 1999 (D99A) by the UN. The updated UN/EDIFACT parser is able to recognize individual messages as well as message dialects and dynamically chooses the appropriate mapping from the mapping JAR files generated before, as shown here:

Dynamic UN/EDIFACT Interexchange parsing

Writing out UN/EDIFACT files

Currently, our SOPERA DI EDI components do not support EDIFACT file generation. Basically, EDIFACT files are just simple text files, and one could simply use a plain template approach to generate EDI. However, we’d like to have additional semantic and syntax checks as well as validation checks. For this purpose we could use an EJC compiler as shown in this figure:

EDI-to-Java roundtrip

The basic idea is that we could generate a set of Java classes based on the UN/EDIFACT mapping files. These classes would then represent segments, segment groups or fields/components specified in the mapping file, and the best part is- you can use them to read EDI as well as write EDI out. It’s similar to the Java API for XML Data Binding, but in this case we bind the Java objects to the EDI content.

Improved UI for SOPERA DI Components

All of the features mentioned above are very useful but our experience shows us that we need to improve the user interface of SOPERA DI EDI components. Right now we are still in the planning and investigation phase. So if you think you have a nice feature proposal we would be glad to hear from you, just leave your comment on this blog post.

Conclusion

All in all with the new functions of the extended EDI processing we can provide a significantly improved user experience that will greatly simplify EDI processing. However, there is still some work to do, but what is clear right now is that all of it will be brought to you by SOPERA and the smooks team as an open source project so you are welcome to participate, contribute, and improve it.

Renat Zubairov Development, Strategy EDI, EDIFACT, smooks, SOPERA, SOPERA DI, Talend

Helios and Swordfish

It’s been a while since my last blog post here. We’ve been quite busy these last few days with the Eclipse 3.6 Helios release. We’ve contributed a very nice feature to the Swordfish SOA Runtime Framework Project: remote deployment. Using this new feature you can deploy locally developed Swordfish services into a remote OSGi server.

Swordfish Remote Deployment Dialog

This is a pretty fancy feature because with it you can take your OSGi bundles, pack them into a feature, and deploy them with one click onto a remote system. Behind-the-scenes, there is a complicated set of plug-in packaging and Eclipse p2 magic which makes sure that all the bundles are deployed in a consistent and atomic manner. Read the Swordfish New and Noteworthy for more information.

SOPERA SOA Tutorial

In this releases we’re also offering you a SOPERA SOA ASF tutorial. We have been working on Swordfish for over a year now, and many people have been asking us how Swordfish integrates itself within the SOPERA ASF product stack. Now we can show you how it works.
Just download the Eclipse SOA package and within the Eclipse IDE GUI, select Help > SOA > Install New Tutorials as shown here:

Eclipse SOA Tutorial

Select SOPERA SOA Tutorial: Rent a Car (OSGi) from the list.

Next, simply follow the instructions shown in the GUI.

The tutorial will demonstrate how to use the pluggable nature of Swordfish Runtime to integrate a standalone ESB Runtime into an enterprise-wide SOA infrastructure based on the SOPERA ASF.

Try it out and send us your feedback. If you have questions or need help, post your enquiries in our forum.

Renat Zubairov Development

SOPERA’s How-To Series

Sometime ago in SOPERA we decided that it might help our users if we were to produce a couple of “How-Tos” in which we would list tips, tricks, or describe the ways in which you can use various SOPERA product components effectively and quickly.

SOPERA’s code generator is currently designed to work only on Microsoft Windows Operating Systems. In this How-To, we’re going to show you how to run the SOPERA code generator in Linux.

Running the SOPERA Code Generator in Linux

To run the SOPERA code generator on Linux:

1. Zip the contents of the /ServiceStudio folder into a zip file.
2. Copy this servicestudio.zip file to you linux user home path (for example, in /home/soadev).
3. Extract the archive file to a directory (for example, into /opt/SOPERA/ServiceStudio).
4. Translate the cmd files set-env.cmd, build.cmd and codegen.cmd to a Linux sh file. Don’t forget to enable the execution of these sh files. They can be found in the folders: ServiceStudio/CodeGenerator , ServiceStudio/CodeGenerator/bin.
5. Create a soft link in the ServiceStudio/CodeGenerator folder:
   ln –s JeeWiz/resources/any/control JeeWiz\\resources\\any\\control
6. Enable the bash scripts’ ant file and and run to execute. The folder can be found in ServiceStudio/CodeGenerator/JeeWiz/external/ant1.7.0/bin.
7. Add a slash in line 36 of the includeSpec.vm file:
   Old: #set( $basicName="file:/${aSchema.xsdTargetFile}"
New: #set( $basicName="file://${aSchema.xsdTargetFile}"


   You can find the file in this folderServiceStudio/CodeGenerator/JeeWiz/SBBresources/SBBservice/control/schema.

8. Now, test your code generator!

Robert Lalyko Development Code Generator, Linux OS, SOPERA Code Generator

Many people working in SOPERA (including our CTO) are using Apple Macs. Around 30% of the visitors to our website are also Mac users. However, so far we haven’t had a native Mac OS X installer for SOPERA ASF products. This doesn’t mean that SOPERA ASF will not work on a Mac, however we don’t have it yet as part of our certified platform.

After a couple of requests from our customers I created two simple “How Tos” that show you how to install SOPERA ASF on Mac OS X:

• Mac OS X SOPERA Infrastructure QuickStart - How to install SOPERA ASF infrastructure/SBB
• Mac OS X SOPERA Tooling Quickstart - How to install SOPERA ASF Tooling (so far only Admin Tool)

If you want to see more on this subject, send us your comments here.

Renat Zubairov Development

How To: Implement Chained Service Calls with Generated Code and Typed PAPI

The Scenario

Let’s say you want service X to call an operation of service Y as a service consumer. Here’s the scenario in the form of a sequential diagram for you to follow:

Now, let’s try implementing this!

Follow these steps:

1. Design a WSDL(SDX/SPDX) for both services.
2. Generate code for the consumer and provider of the Service X.
3. Generate code for the consumer and provider of the Service Y.
4. Implement the business code for the provider of the Service Y.

At this point you’ll have to make a few changes in the generated consumer code of Service Y, ServiceYConsumerImpl.java. These changes are described in this ordered list.

1. For all operations that will be called from Service X, add public methods after the Additional Code section. Implementations of these methods simply delegate the call to the corresponding generated consumer methods
   

   Note that the generated consumer methods cannot be called directly, because they have default access levels and are accessible only from the same package

2. Add the public method getParticipantIdentity() returning the participantIdentity variable.

Here is the sample code

/******************************************************************
**
**  Additional Code
**
**  Put extra (unmodeled) fields and methods after this comment
**
*********************************************************************/

public ElementYResponse operationYExtern(ElementY request) throws
TechnicalException {
return operationY(request);
}

public ParticipantIdentity getParticipantIdentity() {
return participantIdentity;
}

Now Start the Call Operation

This is what you need to do in advance:

1. Add dependencies to the common and consumer projects of Service Y to the provider project of Service X.
2. Implement the business code for the provider of Service X

To call operations of Service Y from Service X’s provider implementation class:

1. Declare and instantiate the consumer of Service Y in ServiceXProviderImpl.java.

/*****************************************************************
**
**  Additional Code
**
**  Put extra (unmodeled) fields and methods after this comment
**
*****************************************************************/
        private ServiceYConsumerImpl consumerY = new ServiceYConsumerImpl();

2. Add start-up consumer code as shown in this code snippet.

/* uid: _startupImpl_uid_ */
 /**
 * This is a hook that is called before the SBB is started up.
 * Add an implementation if you want to initialise other resources
  (e.g. open other connections).
 *
 *     It does not throw any checked exceptions - if there is an error,
 *     the program should either exit or throw an unchecked exception.
 */
 private void startupImpl() throws TechnicalException {

	consumerY.startup(
		     consumerY.getParticipantIdentity(),
		     ServiceYConsumerImpl.getConsumerPolicy());
 }

3. Add shut down consumer code as shown in this code snippet.

    /* uid: _shutdownImpl_uid_ */
    /**
     * This is a hook that is called before the SBB is shut down.
     * Add an implementation if you want to release other resources
       (e.g. close obtained resources).
     *
     *     It does not throw any checked exceptions - if there is an error,
     *     the program should either exit or throw an unchecked exception.
     */
    private void shutdownImpl() {
    	consumerY.shutdown();
    }

4. Use the consumer object to call operations of Service Y:

/* uid: SoperaUID_operationX */
/**
* Synchronously execute a request to operation operationX, request-response
* style (similar to JAX-WS).
*
* @param operationXRequest
* the request
* @return the response
* @throws ParticipantException
*             on technical error
*/
public ElementXResponse operationX(final ElementX operationXRequest)
	throws ParticipantException {
	ObjectFactory ofX = new ObjectFactory();
	ElementXResponse response = ofX.createElementXResponse();
	// ... business code
	try {
		org.sopware.services.exampleuri_y.ObjectFactory of Y
		= new org.sopware.services.exampleuri_y.ObjectFactory();
		ElementY requestY = ofY.createElementY();
		requestY.setIn("Request to service Y");
		consumerY.operationYExtern(requestY);
		} catch (TechnicalException e) {
			throw new ParticipantException(
				"Technical problem by Service Y call: "
				+ e.getMessage(), e);
		}
		// ... business code
		return response;
}

Andrei Shakirin Development Generated Code, Implement Chained Service Calls, Service calls, Typed PAPI

Things have been rather quiet around the Eclipse SOA Intitative. The cause for that lies squarely with the exit of some commercial software vendors from the Industry Working Group shortly before it was to start in the fall of 2009.

I think that speaks volumes about the insecurity that these vendors are facing when dealing with Open Source projects. For the others, like Obeo, itemis & SOPERA whose business models are closely entwined with Open Source projects, the work has gone on. Recently, Engineering, Italy’s biggest system integrator joined the Industry Group in February 2010 and has offered up two new SOA projects: eBPM und eBAM giving the whole initiative a new momentum. As a result of which, half a year later, the Eclipse SOA Industry Working Group will now attend the SOA days at the Deutsche Post officially with a keynote presentation by Mike Milinkovich.

Ricco Deutscher Development, Management, Strategy eBAM, eBPM, Eclipse SOA

We have decided to publish a number of short, easy to follow, “How Tos” in our blog. Here is a short “how to” from our team related to Intalio and P2P.

Peer to Peer (P2P) Communication with Intalio 6.0.013

SOPERA BPM 2.0 allows the deactivation of process to process (peer to peer) communication. This feature is required for the implementation of the dual usage (invoke and provide) of one WSDL in BPM processes. This section describes how to do just that.

Disabling P2P Communication

To disable the P2P communication:

1. Add the attribute usePeer2Peer in the project deploy.xml file.
2. Set this attribute value to false in the project deploy.xml file for the specific partner link

Take a look at this example:


<dd:invoke partnerLink="..." usePeer2Peer="false">;
<dd:service name="..." port="..."/>
</dd:invoke>


That’s all!

Robert Lalyko Development

SOPERA ASF on Mac OS X

Yes, it’s true! You can now install and run SOPERA ASF with very little effort on your Mac OS X. For information on prerequisites, installation instructions and tips, see Mac Quick Start.

Please send us your feedback on the article and let us know if you are interested in finding out more about running SOPERA on Mac OS X.

NOTE: There are two support categories defined by SOPERA, Supported
and Certified. The Mac OS X is neither supported nor certified by SOPERA.

Anne Aloysious Development Mac OS, Mac OS+SOPERA ASF