Team development with WebSphere Integration Developer and WebSphere Process Server: Developing applications using CVS

Geoffrey Beers, Software Engineer, IBM Rochester Francis Dinardo, ISSW, IBM Raleigh Mannie Kagan, ISSW, IBM Toronto Eric Herness, WebSphere Business Integration Chief Architect, IBM Rochester Logan Colby, Software Engineer, IBM Rochester April, 2006 Copyright International Business Machines Corporation 2006. All rights reserved. This article provides detailed steps and usage examples to help you engage in team development using IBM WebSphere Integration Developer Version 6.0.1 and IBM WebSphere Process Server Version 6.0.1. It identifies the artifacts needed for remote version control management, as well as the necessary procedures to develop applications with artifacts remotely managed in a team environment using WebSphere Integration Developer. It is assumes that the reader has basic knowledge of Service Component Architecture (SCA) and Eclipse.

Introduction......................................................................................................................... 2 Describing the application .................................................................................................. 4 Authored versus generated artifacts.................................................................................... 6 Artifact types: derived versus non-derived ........................................................................ 7 Application components and artifacts................................................................................. 9 SCA Component Artifacts .............................................................................................. 9 Exports and Imports...................................................................................................... 10 BPEL............................................................................................................................. 10 Business State Machines............................................................................................... 11 Human Task Manager................................................................................................... 12 Business Rules and Selectors........................................................................................ 13 WSDL Interfaces and Business Objects ....................................................................... 14 Maps and Relationships ................................................................................................ 14 POJOs ........................................................................................................................... 15 Team development with CVS........................................................................................... 15 Developing Process Server applications in a team environment using CVS................ 16 Adding new Process Server projects and artifacts to CVS ........................................... 16 Extracting remote Process Server artifacts from CVS.................................................. 20 Synchronizing files with the CVS repository ............................................................... 22 Committing local changes to CVS................................................................................ 23 Updating local workspace with remote CVS artifacts.................................................. 23 Synchronization considerations with multiple users..................................................... 24 Managing libraries in CVS ........................................................................................... 24 Managing staging modules in CVS .............................................................................. 25 Wiring components in a team environment .................................................................. 26 Hints and tips when working in a team environment ................................................... 27 Conclusion ........................................................................................................................ 28 Resources .......................................................................................................................... 28 About the authors.............................................................................................................. 28 Appendix........................................................................................................................... 29

Introduction
This article describes the configuration of IBM WebSphere Integration Developer (hereafter, referred to as Integration Developer) workspace in Version 6.0.1 and gives careful attention to the management and generation of the various resources of the Service Component Architecture (SCA) applications developed for WebSphere Process Server (hereafter, referred to as Process Server). It is based on the development of an application that leverages most of the capabilities of the business integration development environment including detailed coverage of the most common components and functionality in Process Server and Integration Developer. The scenario leverages the team development facilities of Eclipse and Integration Developer using Concurrent Versioning System (CVS) as the primary tool for team development and application version control. The article begins with an analysis of the

modules core elements as well as those pieces generated by Integration Developer. It then discusses the quintessential components of a module as they pertain to business integration development in a team environment. The final sections of this article describe a detailed methodology, as well as the known problems and workarounds, for team-based Process Server application development. Service-oriented architecture (SOA) is based on the principles of abstraction, implementing a strong and rich interface to a service that will make it reusable in a number of environments. Service Component Architecture (SCA) enables SOA and introduces additional metadata and associated runtime machinery to enable a consistent invocation model for services as well as bindings to popular invocation styles such as Web services and Java Message Service (JMS). SCA also introduces metadata, which captures dependencies (references) that a specific service implementation has on other resources and services in order to function successfully. This leads to a richer solution assembly environment. To enable reuse of services, not only do we need an SOA with SCA at the specification level, we need a set of development tools that facilitate the SOA development methodology. WebSphere Integration Developer does this. Integration Developer enables developers to create new services using a variety of authoring paradigms such as business rules and business processes, with tools to easily and quickly test them. Integration Developer also enables developers to publish new services for access in a variety of ways (Web services, native SCA, and JMS). Given this basic set of capabilities, we have now enabled individual developers for SOA development in a first-class way. Scaling up SOA development means that we need teams of developers working together, building and reusing services and other artifacts that those services depend upon. Libraries enable sharing of Web Services Definition Language (WSDLs), XML Schema Definition (XSDs), and other common building blocks for SOA applications across application modules. The next key capability required for scaling up SOA development is team development. A set of procedures and processes, leveraging existing capabilities in Eclipse and source code control systems is needed. This article provides details on the team development aspect of scaling up SOA development. It begins with background information on team development and discusses the basic premise of team development for this environment. Next, to provide this information in the most effective way, we introduce an application with a number of interesting requirements and capabilities. This application becomes the basis of many of the procedures and tasks centered on the team development that follows. After introducing the application, we provide some basic concepts around source code control and the Eclipse enablement of source code control. This section, entitled Artifact types: derived versus non-derived describes the files involved in enabling each key feature of Process Server, sorting through where each comes from and what purpose each serves in the overall application. This knowledge is then leveraged and built upon

the next section entitled Team development with CVS, where key developer tasks are explained and demonstrated using our example application. This section concludes with some suggestions for building and managing solutions that consist of a number of SCA modules and libraries. Examples based on Integration Developer and Process Server Version 6.0.1 are used throughout this paper. Temporary workarounds and suggested implementation patterns are also noted. Expected changes to procedures due to future product fixes and enhancements are identified as well. In Version 6.0, team development within Integration Developer was only viable through the Resource perspective. Additional support has been added in 6.0.1 to include team development functionality in the Business Integration perspective, thereby seamlessly integrating the development and team management environments within the same view. After reading this article, you will understand the effort needed to scale up SOA team development and the details involved.

Describing the end-to-end eXchange application

The end-to-end eXchange scenario is used to demonstrate the team development functionality of Integration Developer. This scenario demonstrates the use of many major component types, including BPEL, Human Task Manager, Business Rules, Selectors, Adapters, libraries, and import and export bindings. Functionality of Business State Machines (BSM) in a team environment is described in a separate application using an account manager case study. This is primarily an exercise to demonstrate the authored and generated files for each major component type, as well as how these various modules work together in a team development environment. The overall flow of the solution is depicted in the following diagram.

Figure 1. Application overview

The application consists of three primary modules: 1. A service module for each component type. 2. A service library. 3. A J2EE Web project to invoke an SCA component from an external Web project. We cover many of the different component types in the application, including BPEL processes, Business State Machines, Human Task Manager, Business Rules, Selectors, Business Objects, WSDL interfaces, POJOs, and Maps. The application contains the standard J2EE staging modules. The end-to-end scenario uses a library where Business Objects and WSDL interfaces are shared amongst the various service modules. When built, every project in Integration Developer will result in the creation of the following staging modules: App EJB EJBClient Web The staging modules are not visible in the Business Integration perspective, but they can be seen in the Resource perspective. As shown below, after we build our service module the four staging modules are generated.

Figure 2. Staging modules for an application

We introduce the essential elements and imperative files found in the primary service module, as well as those generated in the staging modules. The derived files that are generated from each of these component types will be examined and noted. Additionally, we use a separate J2EE Web Project, which includes a simple JSP application that invokes a Process Server SCA component. This demonstrates a design pattern that places dynamic Web content in a separate Web project defined by the developer, instead of relying upon the generated Web module associated with the primary service module.

Authored versus generated artifacts

The notion of authored and generated artifacts is very important to the structure of the Process Server application, especially in a team programming environment. We define authored artifacts to be those that are (1) required to build the complete application, and (2) created for us when we design our components in Integration Developer. When we build our application, we end up with a file structure that contains our authored artifacts, as well as several generated artifacts that are created by the Process Server builders. The notion of authored artifacts is not strictly limited to those that are obviously created for us when we specify a new component in an Integration Developer editor. For instance, if you add a BPEL process to the Assembly Diagram, an authored .component file is created by the Integration Developer tooling in addition to the .bpel file. Authored files essentially are those core artifacts that are absolutely needed to successfully build the project. As a side note, authored artifacts are those source files that would have to be created if you used a text editor to develop this material instead of using Integration Developer tooling. Any artifact that is not authored is, therefore, said to be generated by the Process Server builders. Generated files are not required for the application to build properly. They will be created at build-time by the Integration Developer builders. When a project build is initiated, any existing generated artifacts may be overwritten with new copies in the source code if the authored files changes. Of course, if the generated files are not present, then they will be created. The four staging modules are entirely generated by the builders. There are circumstances where a developer may place customized dynamic Web content in the staging Web module, but the creation of the module is explicitly performed by the Integration Developer builders.

Artifact types: derived versus non-derived

The concept of authored and generated files is tightly related to a files derivation properties. This property is useful when we manage our modules in a version control system. As we will see, authored artifacts are always non-derived, while generated artifacts are usually derived. Integration Developer has the capability to classify files as either derived or non-derived. To view the derived status for a given file, you must use the Resource perspective and examine the Properties for a given file or folder tree. The Business Integration view now includes support for team project management, but does not include support for viewing folder and file properties.
Figure 3. Derivation properties of an artifact

When the Derived box is checked, it tells us that the file is generated by the Integration Developer builders, and therefore is not authored when a project is created. Upon creating a new component, authored (non-derived) files get created for us. After building this component the generated (typically derived) files are created. In the simplest case, assume we create a Java component. When authored, a non-derived .java file representing the Java source code logic is created for us. After we build the application, an associative .class file will be generated and have derived properties. Some components have a much more complex infrastructure, which includes the generation of several non-derived files. For example, if we create a business state machine, we will get .sacl and .saclex files that define the state machine logic. These files are created by Integration Developer when we create the state machine, and therefore they are not derived. Once the project is built, however, we will get several other files that are generated from the core .sacl logica .bpel file, for instance. Since the .bpel is generated by the Integration Developer builders, it is marked as being

derived. A detailed listing and explanation indicating which files are derived for each component in an Integration Developer business integration project will be discussed in the following section. Of course, in a BPEL application, the .bpel and .bpelex files are considered authored artifacts, and therefore are classified as non-derived artifacts. Furthermore, we can use the knowledge of derived files to assist us with the management of files in a team environment. Since a file marked as derived is generated by Integration Developer, it implies that we do not need to maintain a copy of this file in the CVS repository. We know that if it is not present, it will be regenerated on subsequent builds. In fact, any file noted as derived will not be placed in the CVS repository when the user synchronizes his project with CVS. CVS functionality will be discussed in much greater detail later. The user has the ability to change the derived properties of any file, but this practice is strongly discouraged. If a file marked as derived by Integration Developer has this property changed by the user, then it will be placed in CVS unnecessarily. While this practice is not particularly harmful to a team development project, it does create added confusion to other developers using CVS, since it implies that the file is one of the initial application files created by Integration Developer when the application was created. A perhaps larger problem occurs when a file marked as un-derived is manually changed by the programmer to being derived. When the user synchronized his local workspace with CVS, the file would not be updated properly on the remote CVS repository. There are instances when the derivation properties of a file may need to be changed. We will discuss this in a later section. The four staging modules generated when an application is built are not explicitly marked as derived. Since the staging projects are generated they typically do not need to be managed on CVS. There are certain exceptions with the App staging module where custom deployment descriptor and security role settings are changed, thereby overwriting the default settings generated by Integration Developer. In this case the App staging module would need to be managed in CVS. Similarly, if the developer places any Web content in the generated Web module, then this will also have to be managed by CVS. The EJB and EJBClient modules consist of entirely generated, unalterable code. There is never a viable reason why these two modules should be managed on CVS. Certain cases where CVS management of the staging modules is required will be discussed later. As mentioned above, the folder and file properties must still be viewed under the Resource perspective, in spite of newly added team development functionality added to the Business Integration view. Since only the necessary artifacts are uploaded to CVS via the Business Integration perspective, a full understanding of the derivation properties is not quite as important as it was in Version 6.0. You can make the following assumptions regarding authored and generated and derived and non-derived files: Authored files are always non-derived.

Generated files are usually derived, but sometimes they are non-derived. Eclipse files in your workspace that setup your classpath, runtime, project, or preferences are generated by Eclipse, but they are marked as non-derived. Staging modules are generated, but their folders and file contents are non-derived. Non-derived files are uploaded to CVS when we perform a commit operation. Derived files are not committed to CVS unless we specifically change the properties of the file. Non-derived files that are inside of a folder marked as derived assume the properties of the parent folder, and therefore, are also derived.

Application components and artifacts

Here we will discuss which files get generated in a typical Process Server application. We attempt to cover all of the important business integration components used in Process Server, since each component type has a unique set of authored and generated files. The folder structure used in a team development project is irrelevant. Derived folders and files will not get placed in CVS, whereas non-derived files always will. Of course, there are best practices for organizing certain artifacts in a logical matter. For example, often Business Objects, WSDLs, BPEL processes, and BSMs should each go in their own directory. However, this practice is entirely related to packaging and project infrastructure and has little effect on managing resources in a version control system.

SCA Component artifacts

There are several authored SCA artifacts that are pertinent to Integration Developer and Process Server. Some of the core application behaviors are common across several component types. When a BPEL, BSM, Business Rules, HTM, Selector, or Interface Map component is added to the Assembly Editor, a .component file is created in the primary module. The .component file defines the interfaces that the component exposes as well as any reference partners. If a standalone reference is created in the Assembly Editor, an sca.references file is created. This lists all of the available references defined in the standalone reference. Additionally, any imports or exports added to the wiring diagram have an associated .import or .export file in the root module folder. The sca.module and sca.modulex files are required for all SCA applications. They specify the component implementation and bindings defined in the Assembly Editor, as well as the GUI position of the elements. All of these files are marked as non-derived. When built, a Module stateless session bean is created in the EJB staging module for every Process Server module. Additionally, the BPEL, BSM, and HTM components also have a component.ComponentName stateless session bean generated in the EJB staging module. A ServiceSIBusMessageBean message-driven bean is created for each module as well.

Exports and imports

SCA binding for exports and imports is rather straightforward. When such a binding is generated in the Assembly Editor, an authored .export or .import file is created and placed in the root of the service module. The interface that the binding exposes is also defined in the corresponding .export or .import file. Web Service Bindings are also fairly straightforward. As with SCA bindings, an .export file is created, and the interface that the Web service exposes is defined. When built, a service .wsdl file is created. For SCA and Web services export bindings, an export.ExportName stateless session bean is generated in the EJB staging module. JMS bindings are somewhat more complex. The .import and .export files are considerably more intricate. The resource adapter, connection, and destination are included in the binding. Imports and exports are commonly used for interacting with adapters. An export.ExportName message-driven bean is created for a JMS export. For JCA adapters, the export.ExportName and _import.ImportName message-driven beans are created in the EJB staging module.

BPEL
When a BPEL application is created in Integration Developer, two non-derived files with extensions .bpel and .bpelex appear in the primary service module. The .bpel file specifies the BPEL workflow logic, while the .bpelex file specifies the GUI positioning for the various BPEL activities. There also is an authored Artifacts.wsdl file that is created for the user when a BPEL process is created. When the project is built, there are additional derived files that are introduced in the service module. An authored .mon file for CEI and Audit Log event monitoring gets created. The .mon file serves as a template for user-enabled monitoring. If the BPEL process does not include any monitoring functionality, then this file will have no immediate effect. It does not enable any specific events. However, if monitoring functionality is added to the process, then the monitored activities will be added to the existing .mon file. Although the _bpel.mon file appears to be generated, it is really an authored artifact. Monitoring capabilities are optional, so if this file is not present, then the application will still build properly; it just will not have any event monitoring functionality. Furthermore, several Java (.java and .class) and .smap files get generated in a folder having the same logical folder structure as the target namespace attribute defined in the Business Process Execution Language (BPEL) logic. For example, the target namespace defined in the following BPEL process is: http://CleanPublishBPEL/com/clipsandtacks/process. A lowercase directory tree for the generated files will resemble this target namespace path as: cleanpublishbpel/com/clipsandtacks/process. This can be seen in the file structure below.

Figure 4. BPEL artifacts

Business state machines

Business state machines (BSM) are used to define business applications with state-like functionality. The underlying logic of a BSM is based on BPEL, so the derived files generated in the BPEL application will also apply to those derived in BSM. Assume you create an account management business state machine with the name AccountManagerBSM. When a state machine is authored, Integration Developer will create two files: .sacl and .saclex. The .sacl file defines the state machine logic, and a .saclex file defines the GUI layout for the state machine. When the application is built, there are additional files that get created, which depend on the non-derived .sacl and .saclex files. A .bpel file with the same name as the BSM gets generated, thereby defining the equivalent BPEL. As in the BPEL component, an Artifact.wsdl file is also created, but unlike BPEL the Artifact.wsdl in BSM is derived. Finally, a _bpel.mon event monitoring file for BPEL is created. This automatically disables event monitoring for the generated BPEL file, since the events we are most concerned with are BSM events, not BPEL. This _bpel.mon file is strictly implemented to disable the event monitoring for the generated BPEL process. It is generated by the BSM builders, but marked as non-derived. Optionally, an authored _sacl.mon file will be created if the developer adds event monitoring to the BSM logic. As we also saw with the BPEL application, the BSM application will generate several Java source and class files in a folder structure replicating the target namespace path defined in the state machine logic.

Figure 5. BSM artifacts

Human Task Manager

A .tel file is created in the specified folder when a human task manager component is authored in Integration Developer. Since the Human Task Manager is human and not machine-generated, the implementation details at build and design time are rather straightforward. There are no .java or .class files generated in the primary module. Human task components also support optional event monitoring.
Figure 6. Human Task Manager artifacts

Business rules and selectors

Business rule groups are defined by .brg and .brgt files. Optionally, if a decision table or rule set is created then they will be represented by the non-derived .dtable and .ruleset files. For selectors, .sel and .selt files are created. When the application is built, brg, dtable, and ruleset folders are created in the directory tree where the corresponding .brg, .dtable, and .ruleset files are defined. Derived Java .class files for the business rules specifications are also in these folders when the build is complete. Similarly, selectors will generate derived Java class files in a sel folder where the .sel file is defined. The Java source (.java) files for business rules and selectors are generated (but nonderived) and placed in the modules gen/src folder, and do not appear in the Resource perspective. However, in the Physical Resources view under the Business Integration perspective, the files under gen/src are viewable. These .java files are compiled into the aforementioned .class files, which appear in the respective brg, dtable, ruleset, and sel folders.
Figure 7. Business Rules and Selector artifacts

WSDL interfaces and Business Objects

WSDL interfaces and Business Objects are the most straightforward elements in the Integration Developer model. Since they are defined by .wsdl and .xsd, respectively, no other derived files are created upon building the service module. On a project build, these types do not directly generate any derived files. As a design practice where WSDLs and Business Objects may be used by many modules in the same application workspace, they are often placed in a library.
Figure 8. WSDL and Business Objects artifacts

Maps and relationships

Business Object maps are defined by .map files. Interface maps are similarly defined by .ifm files. Each interface map can be represented by a .component file in the SCA model by dragging the component to the Assembly Editor. Both Business Object and interface maps include support for event monitoring. When built, Business Object maps create a folder structure that matches the target namespace, similar to the generated folder structure generated from BPEL and BSM components. The appropriate Java and .smap files are listed in this folder structure. These files should be marked as derived since they are generated by the builder; however, they are currently appearing as non-derived. There is no harm in uploading these files to a version control system; they will be regenerated in subsequent builds. Relationships and roles are defined by .rel and .rol files, respectively, and they have no generated artifacts.

Figure 9. Maps and Relationships artifacts

POJOs
A POJO is a Plain Old Java Object implementation of an SCA component. The .java file will include the component logic and will be located in the primary module based on the packaging structure defined in the Java code. When built, a .class file will be created in the same folder. Like other components, when a POJO is added to the Assembly Editor, a .component file will be created. In the Business Integration perspective, the POJO will be located in the Java section under Business Logic. In the Resource perspective, the POJO will be located in the Java package path defined by the user. As we see in the Resource perspective below, the POJO is represented by Component1Impl.java.
Figure 10. POJO component artifacts

Team development with CVS

After the application is created in a standalone environment, the mechanics of sharing the application components for team development have now been explored. This section documents the specifics of using eclipses built-in CVS team development support to coordinate Integration Developer workspaces with repositories such as CVS. We examine the process of importing business integration projects from CVS, as well as updating files, synchronizing changes with the CVS repository, and managing versions of

core artifacts. As an extension to the previous section, we will also examine which core artifact files need to be tracked in a CVS environment.

Developing Process Server applications in a team environment using CVS

The general methodology of developing Process Server applications in a team environment is similar to how one would develop other types of CVS-managed projects. Modules stored in CVS can be checked out by valid users, modified, and finally committed back to CVS once the changes are completed. While Integration Developer supports this development model, the method to which this should happen is not as straightforward as developing a team-based Java project. As we have seen, Integration Developer generates several staging modules and derived artifacts when a project is built. Because of this, we must carefully decide how Integration Developer projects and files should be managed in a team environment. New features have been added to Integration Developer 6.0.1 to support team development within the Business Integration view. In the 6.0.0.0 release, team development controls for sharing and managing projects were only available under the Resource perspective or the Physical Resources view. The Business Integration view in version 6.0.1 now includes team development support for the following operations: Add (share) a project to CVS or Clearcase. Synchronize changes between the local application and remote repository. Commit local changes to the remote repository. Update (replace) local workspace artifacts with latest version on remote repository.

Under most circumstances, only the primary module needs to be managed in a team development environment. Because of this, the Business Integration perspective only supports team management of the primary module. In the unlikely circumstance that the developer requires version control management of a staging module, then the Resource perspective will be required.

Adding new Process Server projects and artifacts to CVS

By default, CVS will not commit any files or folders that are marked as derived. As we have learned, the authored files are marked as non-derived, while most of the generated files are marked as derived. Although it is possible to also commit the four staging modules to CVS, we will refrain from doing so since they are generated modules.

Furthermore, the Business Integration perspective has a Show Files option that will show you the authored artifacts in the Physical Resources view for a component. If you rightclick on your component in the Business Integration perspective and select Show Files, it highlights the corresponding authored files in the Physical Resources view for the selected component. For example, if you perform a Show Files operation on a BPEL process, the .bpel, .bpelex, bpel.mon, and Artifacts.wsdl files will be highlighted in the Physical Resources view. As of version 6.0.1, you can now add projects to CVS using the Business Integration view in addition to using the Resource perspective or Physical Resources view in Integration Developer. The Business Integration and Physical Resources views filter out the staging modules, thereby only showing the service module. Since the user is typically only interested in managing the service module, this is usually not a problem. However, if the user needs to manage the staging modules in a remote repository, the Resource perspective must then be used to share the project. When adding a Process Server module to CVS, use these steps: 1. Right-click on the module name and select Team => Share Project. 2. Select a repository type (currently CVS or Clearcase).
Figure 11. Select a repository type

3. Select a location for the remote repository, if necessary. 4. After selecting your user profile, make sure you select Use project name as module name. This is especially important in Integration Developer applications because the sca.module file depends on the module name, and if the module name changes, you will get naming errors later.
Figure 12. Use the project name as the module name

5. Select the entire module name since we will add the entire module.
Figure 13. Add the entire module to CVS

6. You will be notified that you have uncommitted changes that have yet to be shared. Click Yes.
Figure 14. Commit any outstanding changes

7. You will be notified of the number of files you are attempting to commit. Click Yes.

Figure 15. Number of artifacts you are adding to CVS

8. Add an optional comment for version tracking. The files and folder structure will be uploaded to the remote CVS repository and the service module will be available for check out.

Issues when adding modules to CVS

There are some known issues that occur when attempting to add a new module to a CVS repository. Some of these issues are due to the inherent structure of CVS, while others are caused by the module structure generated by Integration Developer. Problem: The commit process uploads empty folders to CVS As we have learned, CVS will only commit those files that are marked as non-derived. Properties for a file or folder can be seen under the Resources perspective or the Physical Resources view. When a module is built, there are several generated folders, Java source and class files, and artifacts such as Business Objects and WSDLs that get generated during the build process. For example, earlier we learned that BPEL generates some of its Java source and class files in a directory structure matching that define in the target namespace attribute of the project. When Integration Developer builders create these generated folders during the build process, it only marks the generated files as derived, not the folders themselves. This is for a very good reason. Assume a developer places an authored Java class file in one of these generated directories. While this is certainly not good practice, there is nothing in Integration Developer that stops the developer from doing this. If the entire folder is marked as derived, then this authored Java file would also inherit the derived property from its parent folder. Therefore, when the user tries to commit this authored Java file to CVS, it will not be notified for upload because the parent folder is derived. By default, the commit process will upload an empty folder structure to the remote CVS repository, even if the files within the folders are entirely derived. There are two ways to handle this. First, when adding projects to CVS, you can choose to remove any folders from the view that it selects for committing. This requires some knowledge of the generated folder structure. Without careful attention, doing this may result in mistakenly excluding folders that really should be in CVS. Second, you can simply upload the

empty folders to CVS. This is the easiest method and will make it much easier for users to manage when they try to commit files on future builds. Realistically, at some point the empty files will be placed there by someone anyway, so adding them in the beginning will serve no harm whatsoever.

Extracting remote Process Server artifacts from CVS

Once a connection is made to CVS, we attain a list of available remote projects that we can check out as modules to our local workspace. When you perform a module check out, you will be essentially extracting the entire service module from CVS. Therefore, there is no reason why you need to create a module before you check out the folder from CVS. The module from CVS will include the necessary .classpath, .project, and .runtime files, so it can be built like any other module. In the Resource perspective you will see the list of modules that you extracted, with the complete folder structure. Likewise, remote projects shown in the Business Integration view are structured like any other Integration Developer project. To differentiate remote CVS projects from local ones, notice that the name of the CVS repository appears in brackets next to the module name. Furthermore, also notice that none of the remote staging projects reside on CVS unless they are explicitly placed there by the user. Since they are considered derived projects, they will be regenerated once the user extracts the primary service module from CVS and builds the project.
Figure 16. Modules checked out from CVS are noted in the Resource perspective

Below we see a remote module within the Business Integration view. Newly added team development functionality in version 6.0.1 allows the user to share and manage version control projects within the Business Integration view, as shown below.
Figure 17. Remote artifacts can also be managed in the Business Integration view

Issues when extracting modules from CVS

Problem: Missing the gen/src folder You may also be notified of an error in your module telling you that the gen/src folder is missing. The gen/src folder contains derived Java files generated by Integration Developer. In the Resource view the gen/src directory is hidden from the user. The only way to observe this directory in Integration Developer is to look under the Physical Resources view in the Business Integration perspective. By default, the eclipse CVS plug-in does not allow users to import empty folder structures. Although the gen/src folder may very well exist on the CVS repository, it will become pruned when the module is extracted from CVS into the local workspace. There are two possible fixes for this problem: 1. Disable the directory pruning option. From the menu, Window => Preferences => Team => CVS, uncheck the Prune empty directories option. Click OK.
Figure 18. Prune empty directories

2. Create a gen/src folder in the primary service module. From the Resource perspective, right-click on the service module and select New => Folder. Unfortunately, the folders have to be added separately. First, add a gen folder and click Finish. Then repeat this process and add src under the newly created gen folder. This problem does not occur so much when you first extract a module. It appears much more prevalently when you are calling updates to CVS. If you should experience this problem, it may be better to disable the directory pruning option in the Preferences. This is a one-time fix, whereas creating the gen/src folder may have to be done repeatedly (this occurs more often with updates see below).

Synchronizing files with the CVS repository

During a team development project many users can check out the same modules without any restrictions. When users make changes to the authored artifacts extracted from CVS, they must be compared or synchronized with the remote copy of the files to coordinate the possible content discrepancies that exist between the local and remote versions of the artifact. In this case, the user will commit his changes to the server. Likewise, user1 may not have made any changes to the artifact in his local workspace, but user2 may have made changes to the artifact and uploaded the newest copy to the server. If user1 synchronizes his workspace with the CVS repository, he will notice that he has a stale copy of the artifact, and hence, will need to update his workspace. Finally, we look at possible conflicts that may occur when, say user1 and user2 both check out a module. User1 makes a few changes to the artifact, synchronizes his changes without problems, and commits his changes to CVS. User2 also makes changes to the same artifact, and synchronizes after user1 has committed his changes. We get a synchronization conflict because user2 now has a file that is out of synch with the CVS server. The basic CVS synchronization issues are: Commit: The user makes changes to an artifact checked out by CVS and uploads the changes to the CVS repository. Update: The user synchronizes his workspace with the repository and realizes his files local files are unmodified, but have newer versions that are available on the server. His local copy is out-of-date; he must extract the most recent copy from CVS. Conflict: The user is trying to commit a file that has already been modified and committed by a different user. In other words, the version currently in CVS is not the version he originally checked out. His artifacts are out of synch with the remote CVS server.

Issues when synchronizing artifacts with CVS

Problem: Files show up as being changed but the files contents are unchanged. Sometimes you notice files that show up as having changes when you synchronize, but when you compare the local and remote versions the contents are identical. The Manifest.mf file, for example, often demonstrates this behavior. To make matters worse, when you try to commit your files, it may tell you that some of your files are out of synch with the server, even though you just ran the synchronize command. The problem here is due to timestamp differences on the local and remote files. Although the local and remote files have the same contents, the timestamp is different, thereby forcing CVS to think that these files are out of synch.

There is a simple command that fixes this problem. If you right-click on your module under the Synchronization tool, you will see an option Clean Timestamps. This removes from view any files showing up as unsynchronized, assuming the only difference they share is caused by inconsistencies in their timestamp.

Committing local changes to CVS

After synchronizing your local workspace with CVS, you are given the option to commit any locally modified files to the remote server. When you commit your files, the file gets updated on CVS with a new version of the artifact created on the CVS server. If there are files in conflict you can analyze the changes and merge the artifacts. You can also perform an Override and Commit. This will commit the local copy of the artifact into the repository and thus remove any of the incoming changes. This action should be taken with great precaution. It is always advised that you look at the differences between the local and remote copy during a conflict. If the problems are trivial or irrelevant, then an Override and Commit can be used.

Issues when committing artifacts to CVS

Problem: Committing your files without synchronizing first. Eclipse allows you the option of committing your files without synchronizing your workspace first. You can do this by right-clicking on the Team => Commit or Team => Override and Commit menu. While this is allowed, it is highly discouraged. If you choose to do this, then it implies that all local changes will be forced to the server and will overwrite any existing conflicts that reside on the CVS repository. Since you will not be synchronizing, you will not see the line-by-line differences that exist between the local and remote copies of the server. There is rarely a good reason to do this action, and it will often cause more harm than good.

Updating local workspace with remote CVS artifacts

Updating your workspace with remote files works very similar to commit, except that you are receiving changes from the server instead of sending them. As with commit, you can update and override any local changes made to your module, but this also should be used cautiously.

Issues when updating artifacts from CVS

Problem: Updating your files without synchronizing first. Like commit, you can also update your local files without synchronizing. For reasons stated above, this should be avoided at all costs. Always synchronize before you update.

Synchronization considerations with multiple users

By default, the components and artifacts defined in Process Server are composed in XML. However, in Integration Developer we are able to open artifacts, such as BPEL, BSM, or the SCA Assembly Editor, in tooling that display this XML data in a userfriendly graphical manner that is easy to understand and abstracts the XML source code from the user. Unfortunately, when CVS synchronizes between the local and remote workspace only the differentiation between the versions source code is analyzed. Although a user creates an application in Integration Developer using user-friendly graphical tooling to describe process workflow, state machine logic, module assembly, or business rules, the CVS tool is only capable of noting differences between the two source code models -- something the user rarely sees. Assume that a user extracts a BSM module from CVS. He makes a few changes to the state machine using the state machine editor and synchronizes his changes with the remote CVS version. Instead of mapping the differences in an editor that resembles the state machine editor, the differences are shown in XML mappings between the local and remote versions of the file. This is not necessarily a bad thing, since the user is the only one currently modifying this component and he knows the effect of the changes being made. However, when multiple CVS users are added to this scenario, it becomes much more complex. Assume there are two users on the system: user1 and user2. Both users extract the same module and unknowingly check it out at the same time. They each begin modifying the state machine logic. User1 adds a few states and variables to the state machine, synchronizes his files without problems, and commits the changes back to CVS. User2, unaware of the changes made by user1, synchronizes his state machine with the remote copy and notices a problem. Since user1 already committed his changes to this file earlier, user2's copy is now out of synch. The CVS compare tool will show the merge points between the two copies and will try to merge the XML code as coherently as possible. Without seeing the state machine in its graphical format, however, accepting the suggested merge points in the Team Synchronization editor is very risky. In a future release of Integration Developer, there may be support for a full GUI mergeand-compare tool. However, as of the current release, merge-and-compare occurs strictly on a line-by-line text basis. Because of the potential conflicts that may occur with textlevel synchronization, users are strongly discouraged from making concurrent updates to Process Server artifacts in CVS. Furthermore, to avoid some of the synchronization problems that may occur it is strongly advised to synchronize often to identify possible synchronization conflicts as early as possible.

Managing libraries in CVS

Additional complexity is added when we introduce libraries to CVS. By definition, libraries can only contain business objects, interfaces, and mapping functionality. Since the module projects are dependent upon the library, changes to artifacts in the library can potentially affect several users.

As is the case in any application where a library project is used, CVS users should take precautions when modifying elements inside of libraries. It is feasibly possible that changes to Business Objects and WSDLs in the library may cause unforeseen incongruities in other service modules that also depend on the library. For instance, assume that user1 is developing a BSM and user2 is developing a BPEL application. Assume that the BSM and BPEL applications are in their own separate module. A library is used for the Business Objects and WSDLs, since the modules implement the same interface. User1 extracts his BSM module from CVS, but to get the state machine to work as desired, he needs to make some changes to some of the Business Objects and WSDL operations in the library. He notices that with the changes to the library artifacts his state machine works as he anticipated. Thinking there are no problems, he commits the changes to CVS and closes his session. Later, user2 logs in to CVS and extracts his BPEL and libraries. Although nobody else has modified the BPEL application, he notices that his application will no longer build properly due to the changes that user1 made to the shared Business Objects and WSDL interfaces. Without knowing it, user1 made changes to the shared library that affected other components and modules. Therefore, when changing shared artifacts managed in any version control system, it is crucial that one is aware of the effects that these changes may have on other modules.

Managing staging modules in CVS

Under normal circumstances, we assume that the four staging modules will be entirely generated by tooling, and therefore will not need to be managed on CVS. However, it may be possible that security role settings or context-root paths in the application deployment descriptor may be customized by the development team. This occurs when traditional J2EE modules, typically external Web modules, are added to the Process Server application. Security roles may be added to the external Web module, thereby modifying the Application deployment descriptor from its generated value. In such cases, it will be required that the App staging module is also managed on CVS. Similarly, the Web staging module may include J2EE dynamic Web content, such as a JSP that will invoke your SCA application. If the JSP logic is placed in the application's generated Web staging module, then the Web staging module must also be maintained on CVS. There is a possibility that the JSP logic may be lost or ignored by the development team since developers may assume this to be a derived resource, and therefore, inadvertently exclude it from the CVS management. Although not required, it is suggested that any Process Server applications that need dynamic Web functionality should create a new Web project and place the Web content in there. This creates another layer of abstraction and avoids the discrepancies may occur when maintaining Web applications inside of the generated Web staging module. Although it is possible to have circumstances where the App and Web staging modules include customized content that must be managed on CVS, the EJB and EJBClient

staging modules consist of entirely generated artifacts. Thus, they will always be recreated when the project is built, and therefore, never need to be managed by CVS. As mentioned above, staging modules can only be managed on CVS using the Resource perspective. Since the staging modules contain artifacts that do not typically need to be managed on CVS, the functionality for managing these generated staging modules is explicitly not included in the Business Integration perspective.

Wiring components in a team environment

After you define your component implementation, you can add the component to the SCA Assembly Editor and wire the component to other components, exports, or import bindings. When the component is added, a .component file is created, which includes the interfaces and reference partners that are bound to the component. Additionally, wiring targets to other components or bindings are defined in the .component file as well. Every time a new component or binding is added to the Assembly Editor, the sca.modulex file is updated to reflect the GUI coordinates of the various SCA components and bindings. It is important to note the creation of the component implementation (for example, the business rule group, BPEL, or BSM) has no immediate correlation to the .component file representing these components. The .component file is only created when you add it to the Assembly Editor, and development of the implementation artifact (.brg, .bpel, .sacl, etc.) is independent from development of the corresponding .component file. In a single developer environment, wiring the components is rather straightforward and manageable. However, due to the interdependencies between the .component, .import, and .export files, as well as the sca.modulex file, wiring the components in a team environment is somewhat untenable. Take this scenario. User1 is creating a BPEL process, which uses a Business Rule and invokes a BSM. User1 adds the BPEL process, business rule, and BSM components to the Assembly Editor and wires them together. Before user1 has a chance to commit his changes, user2 adds the BSM with an export binding and commits the changes to the server. When user1 synchronizes, he notices that the sca.modulex, and BSM.component files are out of synch. As we discussed earlier, merging changes in XML code is very difficult. Because of the problems described, it is important to avoid team development on the Assembly Editor as much as possible. Unlike individual components such as a .bpel process or .sacl BSM, this is harder to manage because ultimately every component in the module will interact with the Assembly Editor at some point. However, think of SCA components as black box elements. If you are assigned a BSM, you can test the behavior of your component rather easily without having to rely on other components or bindings. Assume your BSM references a BPEL process, a Business Rule, and an import. In your local workspace, you can use POJO stubs in a local copy of

the Assembly Editor or use emulators via Test Component to test the viability of the BSM without specifically relying on other components.

Hints and tips when working in a team environment

Here is a bulleted list of tips and proposed best practices that summarize the material that we discussed with regards to team development using CVS. When using libraries, keep in mind that changing a shared BO or WSDL may have unexpected side effects on other components that also use this library. Staging modules are generated -- albeit, non-derived -- and they usually do not have to be managed in a version control system. New features added to version 6.0.1 allow users to manage team projects and libraries -- including adding, committing, and synchronizing -- via the Business Integration view. This eliminates some of the complexity involved when projects are managed via the Physical Resources view or Resource perspective and, in addition, uses the same view for development and team project management. Of course, the ability to manage team projects via the Resource perspective is still available. Team development functionality included in the Business Integration perspective does not have support for managing staging modules. Although staging modules will not need to be managed remotely in most circumstances, there are times when a project may require such management. In such cases, the Resource perspective must be used. Consider using a separate Web project for dynamic Web content; otherwise, you will have to manage the generated Web module in CVS. Avoid having two or more people develop the same artifact at the same time. If synchronization conflicts do occur, the developers should sort out which changes were made instead of relying on CVS merge techniques. When merging files in CVS, you will be merging raw XML code, not standard GUI editors. The support for full user-friendly GUI comparison and merge will be tentatively added in a future release; however, as of now, this process is entirely handled in pure text format. Never commit or update without synchronizing first. Synchronize often. If you have problems with a missing gen/src folder, consider disabling the automatic pruning option. Some files appear out of synch due to timestamp discrepancies. Use the Clean Timestamps option in CVS to automatically get rid of these problems. When you add authored artifacts to your local workspace and commit your changes, you will also add the artifact to CVS. Consider using the Show Files option in the Business Integration perspective to see a list of authored artifacts for a given component.

When you delete an authored file from your local workspace and synchronize with CVS, you will see a - sign notifying you that you will delete the artifact from the remote server. This will remove all traces of the file. Be careful! For BO maps, some of the generated files show up as non-derived, when they really should be derived. This is known for the target namespace generated directory structure in BO maps. As we have discussed, this does not have significant impact on team development. It simply implies that we are placing files on CVS that do not need to be there. When the artifacts are extracted and rebuilt, these specific files will be regenerated. When testing your components in the Assembly Editor, consider using stubs when testing your component. Team-based component wiring can be risky, especially at earlier stages of development.

Conclusion
This paper provided the background and details on accomplishing team development using Integration Developer and Process Server Version 6.0.1. Relevant details around the steps and actions have been outlined and examples of usage have been given. This document focuses on identifying the appropriate artifacts needed for remote version control management, as well as procedures needed to develop applications with artifacts remotely managed in a team environment using Integration Developer. Although CVS is used as the tool for version control management in this document, conceptually, these methods can be applied to other version control management systems such as Clearcase.

Resources
IBM WebSphere Business Process Management Version 6.0 Information Center http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp

About the authors

Geoffrey Beers is a software engineer at IBM in Rochester, Minnesota. He works in the Bringup Lab and SWAT team for WebSphere Process Server. You can reach Geoffrey at gbeers@us.ibm.com. Francis DiNardo is a Consulting IT Specialist in IBM's Software Services for WebSphere organization and operates out of Raleigh, NC. Francis specializes in J2EE Application Development and Enterprise Security and can be reached at fdinardo@us.ibm.com. Mannie Kagan is a WebSphere IT Specialist at IBM in Toronto, Canada. He works as a services consultant for IBM Software Services for WebSphere (ISSW). You can reach Mannie at kagan@ca.ibm.com.

Eric Herness is currently the Chief Architect for WebSphere Business Integration and is from the IBM Rochester, MN, USA development lab. He is a senior member of the WebSphere Foundation Architecture Board and a core member of the Software Group Architecture Board. Eric has been involved product architecture and product development in object technology and distributed computing for over 15 years. You can reach Eric at herness@us.ibm.com. Logan Colby is a software engineer at IBM in Rochester, Minnesota. He is a developer for WebSphere Process Server. You can reach Logan at lcolby@us.ibm.com.

Appendix
Below is a table that includes a listing of the authored and generated artifacts for each component type. Authored artifacts, typically non-derived, must be persisted when managing projects with CVS for team development. On the other hand, generated artifacts are those files that are created from the authored artifacts when the Process Server builders are called. Generated artifacts are usually derived files, and therefore, they do not need to be managed or exported to CVS when sharing team-based projects. Each primary component type is listed below with their corresponding authored and generated artifacts in Table 1. There are certain files and folder structures, such as sca.module and .component files, that are commonly presented in all business modules. The artifacts listed in all projects are listed in their own section below. Table 2 shows the EJBs that are generated for each component type. Table 1. List of authored and generated artifacts
Component Type Common to all modules: Authored Files .component sca.module sca.modulex sca.references MANIFEST.MF .classpath .project .runtime Folders .settings META-INF xsd-includes .bpel .bpelex _bpel.mon Artifacts.wsdl Generated

BPEL

.java .class .smap

Business State Machines

.sacl .saclex _sacl.mon

Files .bpel _bpel.mon .java .class .smap Artifact.wsdl .java .class

Human Task Manager Business Rules

Business Objects WSDL Interfaces POJO Selector Maps

Relationships Exports and Imports

.tel _htm.mon .brg .brgt .dtable .ruleset _brg.mon .xsd .wsdl .java .sel .selt _sel.mon .ifm .map _map.mon _ifm.mon .rel .rol .export .import

.class .java .class .java .class .smap

Table 2. EJB generation for imports and exports Component Type EJB Module Stateless Session Bean (SSB) All Modules BPEL, BSM, and HTM Imports and Exports SCA Import SCA Export JMS Import JMS Export JCA Import JCA Export Trademarks

ServiceSIBusMessageBean Message-driven Bean (MDB) component.ComponentName SSB

Resource reference in ejb-jar.xml export.ExportName SSB Resource reference in ejb-jar.xml export.ExportName MDB _import.ImportName MDB export.ExportName MDB

IBM and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both.

Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others.

IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtml