Broker schema Development

Creating a broker schema

To organize your message flow project resources, and to define the scope of resource names to ensure uniqueness, you can create broker schemas. A default schema is created when you create the message flow project, but you can create additional schemas.

Before you start:

Complete the following steps.

• Creating a message flow project
• Read the concept topic about broker schemas

To create a broker schema:

1. Switch to the Broker Application Development perspective.
2. Click File > New > Broker Schema or right-click any resource in the Broker Development view and click New > Broker Schema.
   You can also press Ctrl+N. This displays a dialog that allows you to select the wizard to create a new object. Click Message Brokers in the left view. The right view displays a list of objects that you can create for WebSphere® Message Broker. Click Broker Schema in the right view, then click Next. The New Broker Schema wizard displays.
3. Enter the message flow project in which you want the new schema to be created. If a message flow project or one of its resources is highlighted when you start the wizard, that project name appears in the dialog box. If a name does not appear in this field, or if you want to create the schema in another project, click Browse and select the correct project from the displayed list. The message flow project list is filtered to show projects in the active working set.
   You can type the project name in, but you must enter a valid name. The dialog box displays a red cross and the error message The specified project does not exist if your entry is not a valid project. You must specify a message flow project; if you select a message set project, you cannot complete the operation.
4. Enter a name for the schema. Choose a name that reflects the resources that it contains. For example, if you want to use this schema for message flows for retail applications, you might give it the name Retail.
   A broker schema name must be a character string that starts with a Unicode character followed by zero or more Unicode characters or digits, and the underscore symbol (_). You can use the period to provide a structure to the name, for example Stock.Common.
5. Click Finish to complete the task.
   If category view is selected in the Broker Development view when you create the schema, you see a message to say that the schema has been created, but it might not be visible in the Broker Development view when it is empty. To show the new schema in the Broker Development view, click Hide Categories on the Broker Development view toolbar.

The schema directory is created in the project directory. If the schema name is structured by using periods, further subdirectories are defined. For example, the broker schema Stock.Common results in a directory Common, in directory Stock, in the message flow project directory.

BROKER SCHEMA

Broker schemas

A broker schema is a symbol space that defines the scope of uniqueness of the names of resources defined within it. The resources include message flows and other optional resources such as ESQL files, Java™ files, and mapping files.

The broker schema is defined as the relative path from the project source directory to the flow name. When you first create a message flow project, a default broker schema named (default) is created within the project.

You can create new broker schemas to provide separate symbol spaces within the same message flow project. A broker schema is implemented as a folder, or subdirectory, within the project, and provides organization within that project. You can also use project references to spread the scope of a single broker schema across multiple projects to create an application symbol space that provides a scope for all resources associated with an application suite.

If you create a new broker schema while in category mode, the empty schema is not visible in the Broker Development view. To show the empty schema in the Broker Development view, click Hide Categories on the toolbar.

A broker schema name must be a character string that starts with a Unicode character followed by zero or more Unicode characters or digits, and the underscore. You can use the period to provide a structure to the name, for example Stock.Common. A directory is created in the project directory to represent the schema, and if the schema is structured using periods, further subdirectories are defined. For example, the broker schema Stock.Common results in a directory Common within a directory Stock within the message flow project directory.

If you create a resource (for example, a message flow) in the default broker schema within a project, the file or files associated with that resource are created in the directory that represents the project. If you create a resource in another broker schema, the files are created within the schema directory.

For example, if you create a message flow in the default schema in the message flow project Project1, its associated files are stored in the Project1 directory. If you create another message flow in the Stock.Common broker schema within the project Project1, its associated files are created in the directory Project1\Stock\Common.

Because each broker schema represents a unique name scope, you can create two message flows that share the same name within two broker schemas. The broker schemas ensure that these two message flows are recognized as separate resources. The two message flows, despite having the same name, are considered unique.

If you move a message flow from one project to another, you can continue to use the message flow within the original project if you preserve the broker schema. If you do this, you must update the list of dependent projects for the original project by adding the target project. If, however, you do not preserve the broker schema, the flow becomes a different flow because the schema name is part of the fully qualified message flow name, and it is no longer recognized by other projects. This action results in broken links that you must manually correct. For further information about correcting errors after moving a message flow, see Moving a message flow.

Do not move resources by moving their associated files in the file system; you must use the WebSphere® Message Broker Toolkit to move resources to ensure that all references are corrected to reflect the new organization.

The following scope and reuse conditions apply when you create functions, procedures, and constants in a broker schema:

Functions

• Functions are locally reusable and can be called by module-scope subroutines or mappings within the same schema.
• Functions are globally reusable and can be called by other functions or procedures in ESQL or mapping files within any schema defined in the same or another project.

Procedures

• Procedures are locally reusable and can be called from module-scope subroutines in ESQL files within the same schema.
• Procedures are globally reusable and can be called by other functions or procedures in ESQL files within any schema defined in the same or another project.

Procedures cannot be used in mapping files.

Constants

• Constants are locally reusable and can be used where they are defined in any ESQL or mapping file within the same broker schema.
• Constants are not globally reusable; you cannot use a constant that is declared in another schema.

If you want to reuse functions or procedures globally:

• Specify the path of the function or procedure:
  • If you want to reuse a function or procedure in an ESQL file, either provide a fully-qualified reference, or include a PATH statement that defines the path.
    If you define the path, code the PATH statement in the same ESQL file as that in which the function is coded, but not within any MODULE.
  • If you want to reuse a function in a mapping file, do one of the following:
    • Qualify the function in the Composition Expression editor.
    • Select Organize Schema References in the outline view. This detects dependent PATHs and automatically updates the reference.
    • Select Modify Schema References in the outline view. You can then select the schema in which the function is defined.
    (You cannot reuse a procedure in a mapping file.)
• Set up references between the projects in which the functions and procedures are defined and used.

Accessing attributes in a message in the MRM domain

When an MRM message is parsed into a logical tree, attributes and the data that they contain are created as name-value pairs in the same way that MRM elements are. The ESQL that you code to interrogate and update the data held in attributes refers to the attributes in a similar manner.

Consider the sample MRM message. The attribute LastName is defined as a child of the Name element in the Customer message. 

Here is an example input XML message:

 

<Customer xmlns:addr="http://www.ibm.com/AddressDetails" 

xmlns:brw="http://www.ibm.com/BorrowedDetails">
   <Name LastName="Bloggs">
      <Title>Mr</Title>
      <FirstName>Fred</FirstName>
   </Name>
   <addr:Address>
      <HouseNo>13</HouseNo>
      <Street>Oak Street</Street>
      <Town>Southampton</Town>
   </addr:Address>
             <ID>P</ID>
   <PassportNo>J123456TT</PassportNo>
   <brw:Borrowed>
      <VideoTitle>Fast Cars</VideoTitle>
      <DueDate>2003-05-23T01:00:00</DueDate>
      <Cost>3.50</Cost>
   </brw:Borrowed>
   <brw:Borrowed>
      <VideoTitle>Cut To The Chase</VideoTitle>
      <DueDate>2003-05-23T01:00:00</DueDate>
      <Cost>3.00</Cost>
   </brw:Borrowed>
   <Magazine>0</Magazine>
</Customer>

When the input message is parsed, values are stored in the logical tree as shown in the following section of user trace:

(0x0100001B):MRM = (
  (0x01000013):Name = (
    (0x0300000B):LastName = 'Bloggs'
    (0x0300000B):Title = 'Mr'
    (0x0300000B):FirstName = 'Fred'
  )
  (0x01000013)http://www.ibm.com/AddressDetails:Address = (
    (0x0300000B):HouseNo = 13
    (0x0300000B):Street = 'Oak Street'
    (0x0300000B):Town = 'Southampton'
  )
  (0x0300000B):ID = 'P'
  (0x0300000B):PassportNo = 'J123456TT'
  (0x01000013)http://www.ibm.com/BorrowedDetails:Borrowed = (
    (0x0300000B):VideoTitle = 'Fast Cars'
    (0x0300000B):DueDate = TIMESTAMP '2003-05-23 00:00:00'
    (0x0300000B):Cost = 3.50
  )
  (0x01000013)http://www.ibm.com/BorrowedDetails:Borrowed = (
    (0x0300000B):VideoTitle = 'Cut To The Chase '
    (0x0300000B):DueDate = TIMESTAMP '2003-05-23 00:00:00'
    (0x0300000B):Cost = 3.00
  )
  (0x0300000B):Magazine = FALSE

The following ESQL changes the value of the LastName attribute in the output message:

SET OutputRoot.MRM.Name.LastName = 'Smith';

Be aware of the ordering of attributes when you code ESQL. When attributes are parsed, the logical tree inserts the corresponding name-value before the MRM element's child elements. In the previous example, the child elements Title and FirstName appear in the logical message tree after the attribute LastName. In the Broker Application Development perspective, the Outline view displays attributes after the elements. When you code ESQL to construct output messages, you must define name-value pairs for attributes before any child elements.

Configuring a message flow at deployment(promote properties)

Configuring a message flow at deployment time with user-defined properties

Use user-defined properties (UDPs) to configure message flows at deployment and run time, without modifying program code. You can give a UDP an initial value when you declare it in your program, or when you use the Message Flow editor to create or modify a message flow.

For an overview of user-defined properties, see User-defined properties.

See the DECLARE statement for an example of how to code a UDP statement.

In ESQL, you can define UDPs at the module or schema level.

After a UDP has been defined by the Message Flow editor, you can modify its value before you deploy it.

To configure UDPs:

1. Switch to the Broker Administration perspective or Broker Application Development perspective.
2. Double-click the broker archive (BAR) file in the Navigator view. The contents of the BAR file are shown in the Manage and Configure page of the Broker Archive editor.
3. Click the Manage and Configure tab. This tab shows the message flows in your broker archive; expand a flow to show the individual nodes that it contains.
4. Click the message flow that you are interested in. The UDPs that are defined in that message flow are displayed with their values in the Properties view.
5. If the value of the UDP is unsuitable for your current environment or task, change it to the value that you want. The value of the UDP is set at the flow level, and is the same for all eligible nodes that are contained in the flow. If a subflow includes a UDP that has the same name as a UDP in the main flow, the value of the UDP in the subflow is not changed.
6. Save your broker archive.

Now you are ready to deploy the message flow. See Deploying a broker archive file.

DECLARE statement

Use the DECLARE statement to define a variable, the data type of the variable and, optionally, its initial value.

You can define three types of variable with the DECLARE statement:

• External
• Normal
• Shared

The following types of broker node can access UDPs(USER DEFINED PROPERTY):

• Compute node
• Database node
• Filter node
• Nodes that are derived from these node types

Take care when specifying the data type of a UDP, because a CAST is used to change the value to the requested DataType.

Example 1:

DECLARE mycolor EXTERNAL CHARACTER 'blue'; 

Example 2:

DECLARE TODAYSCOLOR EXTERNAL CHARACTER;

SET COLOR = TODAYSCOLOR;

where TODAYSCOLOR is a user-defined property that has a TYPE of CHARACTER and a VALUE set by the Message Flow editor.

ESQL variables

ESQL variables can be described as external variables, normal variables, or shared variables; their use is defined in the DECLARE statement.

Types of variable

External

External variables (defined with the EXTERNAL keyword) are also known as user-defined properties (see User-defined properties in ESQL). They exist for the entire lifetime of a message flow and are visible to all messages that pass through the flow. You can define external variables only at the module and schema level. You can modify their initial values (optionally set by the DECLARE statement) by using the Message Flow editor, or at deployment time, by using the Broker Archive editor. You can query and set the values of user-defined properties at run time by using the Configuration Manager Proxy (CMP). For more information, see Setting user-defined properties at run time in a CMP application.

Normal

Normal variables have a lifetime of just one message passing through a node. They are visible to that message only. To define a normal variable, omit both the EXTERNAL and SHARED keywords.

Shared

Shared variables (defined with the SHARED keyword) can be used to implement an in-memory cache in the message flow; see Optimizing message flow response times. Shared variables have a long lifetime and are visible to multiple messages that pass through the flow; see Long-lived variables. They exist for the lifetime of the execution group process, the lifetime of the flow or node, or the lifetime of the node's SQL that declares the variable (whichever is the shortest). They are initialized when the first message passes through the flow or node after each broker startup.

See also the ATOMIC option of the BEGIN ... END statement. The BEGIN ATOMIC construct is useful when a number of changes have to be made to a shared variable and when it is important to prevent other instances seeing the intermediate states of the data.

ESQL statements and what they do

ESQL statements

You can use ESQL statements to manipulate message trees, update databases, or interact with nodes.

The following table summarizes the ESQL statements and what they do.

Statement type	Description
Basic statements:
BEGIN ... END statement	Gives the statements defined within the BEGIN and END keywords the status of a single statement.
CALL statement	Invokes a user-written routine that has been defined using a CREATE FUNCTION or CREATE PROCEDURE statement.
CASE statement	Uses rules defined in WHEN clauses to select a block of statements to execute.
CREATE FUNCTION statement	Like CREATE PROCEDURE, CREATE FUNCTION defines a user-written routine. (The few differences between CREATE FUNCTION and CREATE ROUTINE are described in the reference material.)
CREATE MODULE statement	Creates a module (a named container associated with a node).
CREATE PROCEDURE statement	Like CREATE FUNCTION, CREATE PROCEDURE defines a user-written routine. (The few differences between CREATE FUNCTION and CREATE ROUTINE are described in the reference material.)
DECLARE statement	Declares one or more variables that can be used to store temporary values.
IF statement	Processes a set of statements based on the result of evaluating condition expressions.
ITERATE statement	Abandons processing the current iteration of the containing WHILE, REPEAT, LOOP, or BEGIN statement, and might start the next iteration.
LEAVE statement	Abandons processing the current iteration of the containing WHILE, REPEAT, LOOP or BEGIN statement, and stops looping.
LOOP statement	Processes a sequence of statements repeatedly and unconditionally.
REPEAT statement	Processes a sequence of statements, then evaluates a condition expression. If the expression evaluates to TRUE, executes the statements again.
RETURN statement	Stops processing the current function or procedure and passes control back to the caller.
SET statement	Evaluates a source expression, and assigns the result to the target entity.
THROW statement	Generates a user exception.
WHILE statement	Evaluates a condition expression, and if it is TRUE executes a sequence of statements.
Message tree manipulation statements:
ATTACH statement	Attaches a portion of a message tree into a new position in the message hierarchy.
CREATE statement	Creates a new message field.
DELETE statement	Detaches and destroys a portion of a message tree, allowing its memory to be reused.
DETACH statement	Detaches a portion of a message tree without deleting it.
FOR statement	Iterates through a list (for example, a message array).
MOVE statement	Changes the field pointed to by a target reference variable.
Database update statements:
DELETE FROM statement	Deletes rows from a table in an external database based on a search condition.
INSERT statement	Adds a new row to an external database.
PASSTHRU statement	Takes a character value and passes it as an SQL statement to an external database.
UPDATE statement	Updates the values of specified rows and columns in a table in an external database.
Node interaction statements:
PROPAGATE statement	Propagates a message to the downstream nodes within the message flow.
Other statements:
BROKER SCHEMA statement	This statement is optional and is used in an ESQL file to explicitly identify the schema that contains the file.
DECLARE HANDLER statement	Declares an error handler.
EVAL statement	Takes a character value, interprets it as an SQL statement, and executes it.
LOG statement	Writes a record to the event or user trace log.
RESIGNAL statement	Re-throws the current exception (if any). This is used by an error handler, when it cannot handle an exception, to give an error handler in higher scope the opportunity of handling the exception.