Copyright © Cloud Software Group, Inc. All Rights Reserved

TIBCO Designer Schema Reference

This section contains some introductory information, followed by reference information for each resource in the Adapter Schemas palette.

When you configure a standard adapter, you do not usually add schema to the adapter explicitly. Instead, you specify configuration information and can then interactively select the data the services manipulate. This reference is therefore mainly for developers who perform a custom configuration using Generic Adapter Configuration.

This section discusses the following topics:

•	AESchemas Folder

•	Adapter Schemas Palette

•

Classes

•	Operations

•

Scalars

•

Unions

•

Sequences

AESchemas Folder

When you launch TIBCO Designer, the project tree always includes an AESchemas folder immediately under the top-level folder.

The AESchemas folder is the repository for all schema data used by all applications in your project.

•	When you configure a standard adapter, TIBCO Designer creates schema resources and places them in the appropriate location in the AESchemas folder.

•	When you configure a custom adapter, you create schemas inside the AESchemas folder. You then add schema references to the services your adapter provides. Some examples are given in this chapter.

Adapter Schemas Palette

When you select an item inside the AESchemas folder, for example, a Classes folder or an individual class resource in the project tree, the Adapter Schema palette is displayed in the palette panel.

You use this palette to define schema for your adapter. See Defining Custom Adapter Schema for an example.

Classes

Many TIBCO applications produce or consume data that are structured as objects. These objects are described by schemas.

A Generic Class resource can be used for these purposes:

•	Define a class object to represent schema data for your adapter. See Defining a Class with Attributes and Defining a Class with Operations.

•	Add a class field to your class object. See Adding Class Attributes.

Defining a Class with Attributes

To define a class that describes data your adapter retrieves or publishes, follow these steps:

1.	In the TIBCO Designer project tree, select the AESchemas folder, then the ae folder.

2.	Drag a Folder resource into the ae folder displayed in the design panel and name it appropriately for your adapter.

3.	Drag an AESchema resource into the folder. Open the AESchema resource and select its Classes folder.

4.	In the palette panel, select the Generic Class icon and drag it into the design panel.

5.	For the Class Type field, select Schema, then click Apply.

6.	You can now add attributes to the class. If you are using palette view, you must select the appropriate palette before you can proceed.

You cannot add attributes to a class until you have specified its type.

Adding Attributes to a Class

The attributes of the schema class object define the type of data that the schema object you are creating will allow. To add attributes to a schema class, follow these steps:

1.	Select the class in the project tree.

The palette panel now displays the icons for resources you can add to the class (or the palettes containing the icons).

2.

Drag the icon that represents the type of data for this attribute. For example, you could drag a class into the design panel, then click the Browse icon to select the class. Or you could drag a Generic Scalar (found in the Scalar Types palette) and choose the desired type from the pop-up. You have these choices:

Adding Class Attributes

Adding Union Fields

Adding Sequence Fields

Adding Scalar Fields

For classes that have superclasses, an attribute or operation must not overload or hide one of the same name in a superclass.

3.	Specify the following additional information about the attribute:

Keyfield. Select the check box if this attribute represents a key field, or leave it unchecked if it does not.

Default Value. Provide a default value. This property is not available for all attribute types.

Readable. Select the check box to make the attribute readable, deselect otherwise.

Writable. Select the check box to make the attribute writable, deselect otherwise.

4.	Click Apply.

Adding Class Attributes

To add an attribute whose value must be a class:

1.	Specify the class that should restrict the attribute value, if it does not yet exist.

2.	Select the class to which you want to add the attribute, or drag a Generic Class into the design panel and choose Schema as the type.

3.	With the Schema class selected, drag the class that should restrict the value into the design panel (or click the Browse button with the class field selected).

4.	Click Apply.

See How TIBCO Applications Use Schema Data for more information.

Adding Union Fields

To add an attribute whose value must be a union, you must first have defined one or more Union resources. See Unions:

1.	Specify the union that should restrict the attribute value, if it does not yet exist. Add union members.

2.	Select the class to which you want to add attributes, or drag a Generic Class into the design panel and choose Schema as the type.

3.	Drag the Union resource into the design panel.

You have now specified that union is the choices of attribute values. For example, you could drag both a string and an integer.

4.	Click Apply.

See Unions for more information.

Adding Sequence Fields

To add an attribute of type sequence, you must have first defined a sequence.

1.	Specify the sequence that should restrict the attribute value, if it does not yet exist.

2.	Select the class to which you want to add attributes, or drag a Generic Class into the design panel and choose Schema as the type.

3.	Drag a Generic Sequence from the Sequence Types palette into the design panel.

4.	Specify a Name, Element Type, and length for your sequence. The length is the number of elements in the sequence.

5.	Click Apply.

See Sequences for more information.

Adding Scalar Fields

To add an attribute whose value must be a scalar, follow these steps:

1.	Specify the scalar that should restrict the attribute value, if it does not yet exist.

2.	Select the class to which you want to add attributes, or drag a Generic Class into the design panel and choose Schema as the type.

3.	Drag a Generic Scalar from the Scalar Types palette into the design panel.

4.	Specify a name, then bring up the pop-up to specify the type of scalar.

The values you can choose from are the types available as part of the Adapter SDK class library. See the TIBCO Adapter SDK Programmer’s Guide for information on the mapping of these types to Java or C++ types.

5.	Specify other information as appropriate, then click Apply.

Defining a Class with Operations

To define a class that describes data your adapter retrieves or publishes, follow these steps:

1.	In the TIBCO Designer project tree, select the AESchemas folder, then the ae folder.

2.	Drag a Folder resource into the ae folder displayed in the design panel and name it appropriately for your adapter.

3.	Drag an AESchema resource into the folder. Open the AESchema resource and select its Classes folder.

4.	In the palette panel, select the Generic Class icon and drag it into the design panel.

5.	For the Class Type field, select Operation Schema, then click Apply.

6.	You can now add operations to the class (see Adding Operations to an Operation Class). If you are using palette view, you must select the appropriate palette before you can proceed.

You cannot add attributes to a class until you have specified its type.

Adding Operations to an Operation Class

The following section gives one example for defining an operation. The exact choices you make depend on the operation you want to define.

To add operations to an Operation class, follow these steps:

1.	Select the Operation resource in the project tree.

2.	From the palette panel, drag the Operation icon into the design panel, then:

a.	Name the operation

b.	Click Browse and select the resource that specifies the return type. It could, for example, be a resource in the AESchema/ae/Scalars folder or a predefined class.

c.	Click the One Way check box if this is a one way operation.

3.	Select the parameters folder and drag resources representing the parameter type into the design panel. For example, assume you want to specify an input parameter of type string:

a.	Drag a Generic Scalar into the design panel.

b.	Specify a name, the type (String), and optional direction (In).

In—In parameter. Client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—Only server can set the value and send the reply back to client.

c.	Click Apply.

d.	Specify additional parameters by repeating steps a-c as desired.

4.	Select the Exceptions folder and drag a resource representing the exception type into the design panel. For an error code, you could use a scalar with the appropriate type. You could also specify a class, as follows:

a.	Drag a Generic Class into the design panel.

b.	Specify a name and click Browse to select a class.

c.	Choose AESchemas/ae/MAdvisoryDocument to indicate this exception returns an MAdvisoryDocument instance.

d.	Click Apply.

e.	Specify additional exceptions by repeating steps a-d as desired.

Operations

SDK operations are described in the metadata objects in the repository. The operation description can be shared across TIBCO ActiveEnterprise products and introspected at run time for dynamic invocation.

Implementing ActiveEnterprise operations consists of two tasks:

1.	Using TIBCO Designer to describe the operations to be performed. This includes parameters and exceptions for the operations.

2.	Using TIBCO Adapter SDK classes to implement the behavior in the application code.

Defining Operations

To define an operation, follow these steps:

1.	In the TIBCO Designer project tree, select the AESchemas folder, then the ae folder.

2.	Drag a Folder resource into the ae folder displayed in the design panel and name it appropriately for your adapter.

3.	Drag an AESchema resource into the folder. Open the AESchema resource and select its Classes folder.

4.	In the palette panel, select the Generic Class icon and drag it into the design panel.

5.	For the Class Type field, select Operation Schema, then click Apply.

6.	Select the Operation Schema class in the project tree. From the palette panel, drag an Operation into the design panel.

7.	Specify the following information for the operation:

Name. Define the operation name.

Returns: Click Browse and select the return type for the operation. It could, for example, be a resource in the AESchema/ae/Scalars folder or a predefined class.

Oneway. Click this check box if the operation can be invoked without waiting for a return value or acknowledgment.

8.	Select the Parameters folder of the operation. From the project tree, drag in the resources representing the parameter types. See Defining Operation Parameters.

9.	Select the Exceptions folder of the operation. From the project tree, drag in the resources representing the exception types.

Defining Operation Parameters

When you define an operation, TIBCO Designer automatically adds two folders:

Operation Parameter Folder

Use this folder to drag in resources representing the parameter types, as discussed in the following sections.

•	Parameters of Type Class

•	Parameters of Type Sequence

•	Parameters of Type Scalar

•	Parameters of Type Union

Operation Exceptions Folder

Use this folder to drag in resources representing the exception types, as discussed in the following sections. See Defining Exception Parameters.

Parameters of Type Class

If you want to add a parameter that has a Schema Class as a type, follow these steps:

1.	Create the operation, as discussed in Defining Operations.

2.	In the project tree panel, double-click the Parameters folder.

3.	Select a class in the project tree and drag it into the design panel, or click Browse and find the class you want to use.

4.	Select the operation direction.

In—In parameter. The client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—Only the server can set the value and send the reply back to client.

5.	Click Apply.

Your operation now expects a parameter which has the class you selected as its type.

Parameters of Type Sequence

If you want to add a parameter that has a sequence as a type, follow these steps:

1.	Create the operation, as discussed in Defining Operations.

2.	In the project tree panel, double-click the Parameters folder.

3.	Select a sequence in the project tree and drag it into the design panel, or click Browse and find the class you want to use.

4.	Select the operation direction.

In—In parameter. The client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—Only the server can set the value and send the reply back to client.

5.	Click Apply.

Your operation now expects a parameter which has the sequence you selected as its type.

Parameters of Type Scalar

If you want to add a parameter that has a scalar as a type, follow these steps:

1.	Create the operation, as discussed in Defining Operations.

2.	In the project tree panel, double-click the Parameters folder.

3.	Select a scalar in the project tree and drag it into the design panel, or click Browse and find the class you want to use.

4.	Select the operation direction.

In—In parameter. The client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—Only the server can set the value and send the reply back to client.

5.	Click Apply.

Your operation now expects a parameter which has the scalar you selected as its type.

Parameters of Type Union

If you want to add a parameter that has a union as a type, follow these steps:

1.	Create the operation, as discussed in Defining Operations.

2.	In the project tree panel, double-click the Parameters folder.

3.	Select a union in the project tree and drag it into the design panel, or click Browse and find the class you want to use.

4.	Select the operation direction.

In—In parameter. The client can set the value and invoke the operation.

In/Out—Both client and server can set the value.

Out—Only the server can set the value and send the reply back to client.

5.	Click Apply.

Your operation now expects a parameter which has the union you selected as its type.

Defining Exception Parameters

When you define an operation, TIBCO Designer creates an Exceptions folder for you. You can specify the type of exceptions the operation should return as follows:

1.	Create the operation, as discussed in Defining Operations.

2.	In the project tree panel, double-click the Exceptions folder.

3.	Drag the object representing the type of exception you wish to have delivered into the design panel. For example, for an exception of type MAdvisoryDocument, select an MAdvisoryDocument object.

4.	Click Apply.

5.	Add more exceptions to the operation as needed.

Scalars

Within TIBCO Designer, the term Scalar refers to a primitive object that describes a data type, such as int, long, char, byte, and date. You select the appropriate folder (for example, ae or sql) and object to determine what kind of primitive data type describes the object and which attributes must therefore be set.

The resources in the ae folder correspond to the types available for SDK adapters.

When an adapter repository is created, a number of scalar objects are included by default.

In addition, you can work with parameterized primitive data types (for example, ae/fixed, ae/binary, ae/char), where you can derive an infinite number of types from a base type by changing various data type attributes. You can use these types, for example, to create a bounded binary or bounded char type. If there is a base data type, then it will be pre-loaded, but you are required to create any other instances as you need them, just as you would for sequence types.

You can use one of the scalar resources that are already included with TIBCO Designer, or define a custom scalar used by your application.

To define a custom scalar:

1.	In the project tree, select one of the folders inside the Scalars folder in the project tree or, to define a new scalar type, create a new folder first.

2.	From the palette panel, drag a Generic Scalar into the design panel.

3.	In the configuration panel, specify the information about the scalar, then click Apply.

To add a scalar attribute to a custom class:

1.	In the project tree panel, select the Classes folder.

2.	In the palette panel, select a Generic Class and drag it into the design panel.

3.	In the configuration panel, select Schema as the class type.

4.	To add a scalar attribute, select the new schema class, then drag a Generic Scalar from the palette panel into the design panel.

5.	Specify the information about the attribute you have added:

Name—Name of the attribute

Type—Select the appropriate type from the pop-up.

Default Value—Specify the default value for this field. This information is optional and no type checking is performed.

Keyfield—Select if this is a key field.

Readable—Select if you want for this field to be readable.

Writable—Select if you want for this field to be writable.

6.	Click Apply.

Unions

Unions may be placed alongside classes within a Classes folder. Like classes, unions are containers of data items, but the contents of a union are alternatives. Only one alternative is actually present in the union instance. Like classes, unions may have an associated property list.

Unions have a name and have one or more union members. Each union member, in turn, has a name and a type. Union and union member elements may have attributes.

Defining Union Objects

Define one or more Union objects as follows:

1.	Select the Union folder.

2.	From the palette panel, drag a Generic Union into the design panel.

3.	Give the Union a name, then add members to the Union.

Adding Union Members to Union Objects

When you specify the union members for a union, TIBCO Designer creates references to the object you add. This section discusses the process for the different resource types:

•	Adding Class Reference Union Members

•	Adding Sequence Reference Union Members

•	Adding Scalar Reference Union Members

•	Adding Union Reference Union Members

Adding Class Reference Union Members

When you add a class union member to a union, TIBCO Designer creates a class reference. To define union members that are classes, follow these steps:

1.	Select a union in the project tree.

2.	From the project tree, drag an existing class, for example, an MBusinessDocument into the design panel.

TIBCO Designer creates a reference to MBusinessDocument and makes it the first union member.

3.	Drag a second class, for example, an MAdvisoryDocument into the design panel.

TIBCO Designer creates a second class reference.

If you now add the union as an attribute to a schema class and assign that schema to an endpoint, the endpoint will only accept data of type MBusinessDocument or MAdvisoryDocument.

You can add more than 2 class references as union members. You can also mix class references and other references.

Adding Sequence Reference Union Members

When you add a sequence union member to a union, TIBCO Designer creates a sequence reference. To define union members that are sequences, follow these steps:

1.	Select a union in the project tree.

2.	From the project tree, drag an existing sequence into the design panel. See Sequences.

TIBCO Designer creates a reference to the sequence.

3.	From the project tree, drag an second sequence into the design panel.

TIBCO Designer creates a reference to the second sequence.

4.	If you now add the union as an attribute to a schema class and assign that schema to an endpoint, the endpoint will only accept data that either match one or the other sequence.

You can add more than 2 sequence references as union members. You can also mix sequence references and other references.

Adding Scalar Reference Union Members

When you add a scalar as a union member to a union, TIBCO Designer creates a scalar reference. To define union members that are scalars, follow these steps:

1.	Select a union in the project tree.

2.	From the project tree, drag a scalar into the design panel. See Scalars.

TIBCO Designer creates a reference to the scalar.

3.	From the project tree, drag a second scalar into the design panel.

TIBCO Designer creates a reference to the second scalar.

4.	If you now add the union as an attribute to a schema class, and assign that schema to an endpoint, the endpoint will only accept data that match either one or the other scalar.

You can add more than 2 scalar references as union members. You can also mix scalar references and other references.

Adding Union Reference Union Members

When you add a union as a union member to an existing union, TIBCO Designer creates a union reference.

To define a union members that are, in turn, unions, follow these steps:

1.	Select a Union in the project tree.

2.	From the project tree, drag a union into the design panel. See Unions.

TIBCO Designer creates a reference to the union.

3.	From the project tree, drag a second union into the design panel.

TIBCO Designer creates a reference to the second union.

4.	If you now add the union as an attribute to a schema class, and assign that schema to an endpoint, the endpoint will only accept data that match either one or the other union, that is, any of the elements in either union.

You can add more than 2 union references as union members. You can also mix union references and other references.

Sequences

Sequence objects describe ordered sets of the same type, for example, an ordered set of integers. The sequence is described by its optional maximum length and the type of element in the sequence. Because the sequence is parameterized both by length and element type, there are an infinite number of sequence types.

Create a sequence as follows:

1.	Select the Sequence folder.

2.	From the palette panel, drag a Generic Sequence into the design panel.

3.	In the configuration panel, select the name, type of the elements, and length of the sequence.

The maximum length is the number of elements in the sequence.

Associations

An association has two endpoints and each association has attributes such as multiplicity and navigability.

Association Types

To better support mapping to relational databases, the XML standard defines an association type, which is one of the following:

•	CONTAINMENT. Implies that an instance of class A "owns" one or more instances of class B. No other class has ownership of the same B instance. If class A is deleted, logically the B instance should be deleted also.

•	REFERENCE. An instance of class A is associated with zero or more instances of class B. The B instances may be referenced by more than one instance of A. This is the most general form of association and is the default if no type is specified.

•

CONSTRAINT_REF. An instance of class A and an instance of class B together contain enough key information to uniquely associate them with an instance of class C. Deletion of A or B instances should cause deletion of all C instances which are no longer referenced. The relation of A or B to C is of type CONSTRAINT_REF.

A Note on Multiplicity

Both ends of an association can have a multiplicity. For example, a 1 to 1 relation has multiplicity = 1 on both ends. One to n (i.e. unlimited) has 1 at one end and -1 (unlimited) on the other. In these cases, there is only one multiplicity number and minMultiplicity and maxMultiplicity will be equal.

In rather rare cases, you would specify a different minimum and maximum. One example given in the "UML Distilled" book is that a car can have 2 to 4 doors. So in this case the "car" end of the association would have multiplicity 1 and the "door" end would have minMultiplicity = 2 and maxMultiplicity = 4.

See any reference on UML for more details.

Copyright © Cloud Software Group, Inc. All Rights Reserved