Appendix D Creating C Components

Define component interface and properties

The definition of a C component specifies the interfaces that the component implements as well as its other properties.

The component's transaction property determines how it participates in transactions. The threading property imposes constraints on concurrent execution of the component.

Define the component's interfaces

All component interfaces for Jaguar components are defined in CORBA IDL modules that are stored in Jaguar's IDL Repository. Chapter 6, "Defining Component Interfaces" describes how to define IDL interfaces.

Component developers typically use one of the following to define the interface or interfaces that their component implements:

Use existing interfaces from Jaguar's IDL Repository
In some cases, client and server component developers may have agreed upon an existing interface or several interfaces that your component must implement. In this case, it is up to you, the component developer, to implement the agreed-upon interface. Jaguar stores HTML documentation for all interfaces in the IDL repository in the html/ir subdirectory of your Jaguar installation.
Define a new IDL interface or interfaces
If you are defining the interface yourself, you can use Jaguar Manager to create a new interface for the component. Chapter 6, "Defining Component Interfaces" describes how.

IDL interfaces for C components cannot have create and destroy methods. These conflict with the C create and destroy functions that are called when your component is instantiated and destroyed, respectively.

Transaction property

The component's transaction property determines how it participates in transactions. You can view and change this property using the Transactions tab of the component's property sheet.

When you mark a component as "Requires Transaction," commands that the component sends to third-tier database servers are automatically performed within a transaction. By default, components are not transactional.

Transactional component attribute describes the settings for this attribute. Chapter 3, "Understanding Transactions and Component Lifecycles" introduces the Jaguar transaction processing model.

Instance properties

The Instances property imposes constraints on the concurrent execution of the component in different threads. You can view and change these properties using the Instances tab of the component's property sheet.

For a single-threaded component, multiple instances may exist simultaneously, but only one can be active at any one time. Jaguar synchronizes instantiations, method invocations, and destructions of all instances. Use the single-threaded model if your component shares volatile global data or stateful resources between instances. For example, volatile global data might be a counter that is stored in a global variable. Sharing a stateful resource would occur if, for example, every component instance opened the same file and wrote text to it. Either example requires the single-threading model. To enable single-threading, do not select any of the options in the Instance Properties tab.

The following settings specify the constraints that are placed on concurrent execution of different instances of the component. The choices are:

Concurrency - Multiple invocations can be processed concurrently; that is, multiple instances can be simultaneously active on different threads. The component must be thread-safe. Use this setting if the component code uses no volatile global data and does not share stateful resources (such as a file) among instances. This threading model offers the highest performance.
The Jaguar shared properties feature provides a means to share data safely among instances of a multiple-threaded component. See "Share data between C or C++ components" for more information.
Bind Thread - Instances are bound to the creating thread. The component uses thread-local storage. The Bind Thread check box determines whether a component instance is always invoked in the same thread or can be invoked on any thread. If Bind Thread is not selected, then Jaguar can invoke the component's methods with any thread.
Do not select this check box, unless your component uses thread-local storage. Jaguar provides no APIs for thread-local storage, but you can issue thread system calls from the C component code. Do not use thread-local storage if you are implementing new components. Instead, use the JagGetInstanceData and JagSetInstanceData routines to associate data with a specific component. If you incorporate existing code that uses thread-local storage into a C component, select this check box.
Pooling - Instances are pooled after a commit or rollback.
Sharing - A single shared instance services all client requests. Only one instance of the component can exist at any one time. Attempts to create new instances when one already exists will fail. In this model, only one instance of the component may exist at any one time. Attempts to create new instances when one already exists will fail. This option offers the worst performance. Select this check box only if the logic in your code requires that only one component instance exist at one time.