Choosing the project structure when you create a message map

In IBM® Integration Bus, you can create a message map in an application project, a static library project, a shared library project, or an integration project.

About this task

You can use any of the following types of resources in a message map:

Many of these resources can be defined in the same project as the map or in a different one; however, for JSON schema and REST API swagger documents, the map must be in the same project container. When a resource is defined in a different project to the map, the project where the map is defined must reference it.

XML schema models and DFDL data models
When you define your message model by using a global XML schema or a DFDL model, consider the following rules:
  • You can have the map and any schema definitions that are used in the map in the same project. The project can be a static library project, a shared library project, or an application project.
  • You can have any schema definition that is used in the map in a static library project and the map in an application project.
  • You can have any schema definition that is used in the map in a shared library project and the map in a different shared library project.
    Note: The XML schema files that are defined in the application project cannot access XML schema files that are defined in a shared library.
  • You can have any schema definition that is used in the map in a shared library and the map in an application project.
  • You can have any schema definition that is used in the map in a static library project and the map in an integration project.
User-defined models
When you use user-defined elements in your message model and you define these elements by using a global XML schema, consider the following rules:
  • You can have the map and any schema definitions that are used in the map in the same project. The project can be a static library project, a shared library project, or an application project.
  • You can have any schema definition that is used in the map in a static library project and the map in an application project.
  • You can have any schema definition that is used in the map in a shared library project and the map in a different shared library project.
  • You cannot have the schema definitions that are used in the map in a shared library and the map in an application project. The Graphical Data Mapping editor reports error CWMSL209E if you break this rule.
  • You can have any schema definition that is used in the map in a static library project and the map in an integration project.
Submaps
When you use submaps in a message map, consider the following rules:
  • You can have the map and submap in the same project. The project can be a static library project, a shared library project, or an application project.
  • You can have a submap that is used in the map in a static library project and the map in an application project.
  • You cannot have a submap that is used in the map in a shared library and the map in an application project. The Graphical Data Mapping editor reports error CWMSL209E if you break this rule.
  • You can have a submap that is used in the map in a static library project and the map in an integration project.

Java code
When you define transformations in your map that use Java code, you can define a map in a static library project, a shared library project, an application project, or an integration project. You can define the Java code in one or more Java projects. Your map project must reference these Java projects.
Note: When the map uses Java code available in a shared library, you must create the map in the shared library project where the Java code is available.

ESQL routines
When you define transformations in your map that use ESQL code, consider the following rules:
  • You can have the map and the ESQL code that is used in the map in the same project. The project can be a static library project, a shared library project, an application project, or an integration project.
  • You can have the ESQL code in a static library project and the map in an application project, that references this static library. 
  • You can have the ESQL code in a shared library project and the map in a different shared library project that has a reference to it. 
    Note:
    • When you store ESQL files in a shared library, you must place the ESQL files inside a schema that is not the default empty schema.
    • Each shared library can have one or more ESQL files in one or more ESQL schemas.
    • The schema in a shared library must be unique:
      • An application or a shared library cannot reference two shared libraries that have ESQL in the same schema.
      • An application with ESQL in schema A cannot reference a shared library with any ESQL in schema A.
  • You can have the ESQL code in a static library project and the map in an integration project.
JSON schema and REST API Swagger models

When you define your message model by using JSON schema or REST API Swagger models, ensure that you are aware of the requirements specified in JSON schema requirements for message maps.

Procedure

Choose one of the following project structures based on the resources that are used in the map if you want to update a map without redeploying your application:

  • If the map includes XML schemas, DFDL models, or both, create the map and associated resources in one or more shared libraries. Reference the shared library project that contains the map from the application project.
  • If the map includes XML schemas, DFDL models, and user-defined elements, create the map and the user-defined elements in the same shared library project. You can use the same or different shared library projects for the other resources. Reference the shared library project that contains the map from the application project.
  • If the map includes XML schemas, DFDL models, and transformations that use ESQL code, create the map and the ESQL files in shared library projects. You can use the same or different shared library projects for the other resources. You must define the ESQL files within a schema. The schema names that are used by all the projects that contain ESQL files must be unique. Reference the shared library project that contains the map from the application project.
  • If the map includes XML schemas, DFDL models, and transformations that use Java code, create the map in the shared library project where the Java code is available. Reference the Java project from the shared library project.
  • If you want to map between different versions of an XML schema, where both versions might declare the same elements and types and cannot coexist in one application, you can build one shared library that contains version 1 of an XML schema file, and another shared library that contains version 2. You can then build a map that references the XML schema files in the shared libraries and maps between the two versions. At deployment time, separate models are built for each of the shared libraries. Therefore, no clash results from the duplicated elements and types.
  • If the map includes JSON schema, create the map and JSON schema in a single shared library. Reference the shared library project that contains the map from the application project that contains the mapping node.
  • If the map includes REST API, and optionally JSON schema (or both), create the map and JSON schema in the REST API project.