Installing components  Running components externally

Chapter 4: Defining Components

Configuring component properties

The Component Properties window configures the settings that EAServer uses to load the component and invoke its methods. Component properties are organized on the following tabs:

Tab

Description

Component properties: General

Defines basic information about the component, including the component type and implementation details such as the Java class name or the C++ library name.

Component properties: Transactions

Defines the components transactional properties, such as how the component participates in transactions and whether the component explicitly commits its work.

Component properties: Instances

Defines how instances of the component are managed, including instance creation, thread binding, and client/component bindings.

Component properties: Environment

For EJB 2.0 or 1.1 components, allows you to specify read-only site specific data for use by the component.

Component properties: EJB Local Refs

For EJB 2.0 components, allows you to configure aliases for EJB components that this component calls using EJB local references.

Component properties: EJB Refs

For EJB 2.0 or 1.1 components, allows you to configure aliases for components called by this component.

Component properties: Resource Refs

For EJB 2.0 or 1.1 components, allows you to configure aliases for resources used by the component such as JavaMail sessions or JDBC connections.

Component properties: Resource Environment Refs

For EJB 2.0 components, configures logical names for objects administered by EAServer.

Component properties: Role Refs

For EJB 2.0 or 1.1 components, allows you to map role names used in method permissions to role names defined in the EAServer repository.

Component properties: Resources

Configures properties that govern the component’s use of server and database resources.

Component properties: Persistence

Specifies the primary key type for EJB entity Beans, and configures properties used to save state information for stateful components that can fail over between servers in a cluster.

Component properties: Run-As Identity

For EJB 2.0 components, specifies the authentication credentials that are used when methods call other components..

Component properties: Run-As Mode

For EJB 1.0 components, specifies the user name and password that are used for intercomponent calls to components installed in the same server or cluster.

Component properties: MDB Type

Applies to Message-Driven Bean (MDB) components only. See “Message-driven beans” for more information.

Component properties: Mirror Cache

Configures properties required to support in-memory failover for stateful components running in a cluster. See “Mirror Cache tab component properties” for more information.

Component properties: Java Classes

Configures the custom class list for Java and EJB components.

Component properties: Additional Files

Configures the file set to be included when the component is exported in Jaguar JAR format or replicated to another installation using the synchronize feature.

Component properties: JAXP Support

For EJB 2.0 components, configures the XML parser implementations used by the component.

Component properties: Advanced

Allows you to manually edit component property settings in the EAServer configuration repository. For advanced users.


Component properties: General

The General tab defines basic information about the component, including the supported IDL interfaces, the component type, and implementation details. If you imported a Java or ActiveX component, these properties have already been configured correctly by the import process. Table 4-1describes the window controls.

Table 4-1: General tab component properties

Property

Description

Notes

Description

Specifies description of the component. The description can be up to 255 characters.

Enter a comment that describes the purpose of the component.

Codeset

(PowerBuilder, C, and C++ components only)

Specifies the name of the coded character set used by a C or C++ component. By default, the component uses the server’s coded character set (specified on the General tab in the Server Properties window).

This field does not display for Java and ActiveX components. These components always use 16-bit Unicode.

For the list of supported values, list the subdirectories of the charsets directory. Each subdirectory matches the name of a supported character set.

Input values for string parameters (and string fields within complex datatype values) are converted to this code set before each method invocation. Upon return, output values are converted from the component’s code set to the client’s code set.

NoteIf your C or C++ component uses Client-Library connection caches, you cannot specify a code set that is different than the server code set. Character data read over a cached Client-Library connection is always in the server’s code set.

Component Type

Specifies the type of the component, which can be:

EJB - Stateless Session Bean A stateless session bean EJB component.

EJB - Stateful Session Bean A stateful session Bean EJB component.

EJB - Entity Bean An entity bean EJB component.

EJB - Message Driven Bean An EJB component that responds solely to JMS messages and lacks a client interface.

Java - CORBA A Java component that uses the Java/IDL datatypes as defined by the CORBA specification for IDL-to-Java type mappings.

Java - JDBC A Java component that uses the JDBC column types for parameter and return types.These type mappings are deprecated. See “Choose implementation datatypes”.

PowerBuilder NVO A PowerBuilder nonvisual object adapted to run as an EAServer component.

COM/ActiveX An ActiveX component adapted to run as an EAServer component.

C++ A C++ class adapted to run as an EAServer component.

C A collection of C routines adapted to run as an EAServer component.

EJB components must be implemented in accord with version 1.0, 1.1, or 2.0 of the Enterprise JavaBeans specification. Version 2.0 is recommended for new development.

ActiveX components are supported only in the Windows version of EAServer. All other component types can run on any platform that is supported by EAServer.

PowerBuilder components should be configured and deployed using the PowerBuilder IDE. Otherwise, EAServer Manager settings may be overwritten when you redeploy from your PowerBuilder project. See the PowerBuilder Application Techniques manual for more information.

EJB Version

only for EJB components

Choose to match the EJB specification version number. EAServer’s interaction with the component is governed by the specification version.

Version 2.0 is recommended for new development.

CMP Version

only for EJB 2.0 entity beans

For EJB 2.0 entity beans that use container-managed persistence (CMP), sets the CMP version number. If you do not specify a value, the default is 1.1.

In EJB 2.0 entity beans, you can use the CMP models from the EJB 2.0 or EJB 1.1 specifications. Version 2.0 is recommended for new development. Version 1.1 allows you to use existing implementation code that requires the EJB 1.1 CMP model.

Bean Class

only for EJB components

The name of the class that implements the bean, in Java dot notation.

MDB Class

only for EJB MDB components

The name of the class that implements the message-driven bean, in Java dot notation.

JNDI Name

only for EJB components

The unqualified name used by client applications to look up the bean’s home interface in the naming service. For example:

finance/account

The fully qualified name is obtained by appending the JNDI name to the server’s initial naming context, for example:

/finserver/finance/account

If you do not specify a name, the default is package/component, where package is the EAServer package name, and component is the component name.

Home Interface Class

only for EJB components

The Java class that defines the bean’s home interface, in Java dot notation.

This field is read only. The class name is determined from the IDL home interface. You can add, view, or edit the IDL home interface using the component’s interfaces folder.

Remote Interface Class

only for EJB components

The Java class that defines the bean’s remote interface, in Java dot notation.

This field is read only. The class name is determined from the IDL remote interface. You can add, view, or edit the IDL remote interface using the component’s interfaces folder.

Local Home Interface Class

only for EJB components

The Java class that defines the bean’s local home interface, in Java dot notation.

Blank if the bean does not have local interfaces.

This field is read only. The class name is determined from the IDL home interface. You can add, view, or edit the IDL home interface using the component’s interfaces folder.

Local Interface Class

only for EJB components

The Java class that defines the bean’s local interface, in Java dot notation.

Blank if the bean does not have local interfaces.

This field is read only. The class name is determined from the IDL remote interface. You can add, view, or edit the IDL remote interface using the component’s interfaces folder.

Primary Key Class

only for EJB entity Beans

The Java class that defines the entity bean’s primary key type, in Java dot notation.

This field is read only. The class name is determined from the IDL struct type that defines the bean’s primary key. You can add a primary key type to a module listed in EAServer Manager IDL folder. Typically the bean’s primary key structure, home interface, and remote interface are defined in the same IDL module.

To set the bean’s IDL primary key type, enter the type name in the Primary Key field on the Persistence tab.

Fully Qualified Java Class

only for non-EJB Java components

The fully qualified name of the Java class file that implements the component’s methods, specified in Java dot notation, as in:

com.yourcorp.YourCompImpl

DLL Name

only for C and C++ components

The name of the Windows DLL or UNIX shared library that contains the component methods. You can omit platform standard file extensions if desired (such as .dll on Windows or .so on Solaris).

Before running the component, the library files must be copied to cpplib subdirectory in the EAServer installation directory.

C++ Class

(only for C++ components)

The name of the C++ class that implements the component.

C++ Executable

(only for C++ components)

The name of an external process in which the C++ component runs.

Run the component externally if you do not completely trust the implemenation not to crash. See “Running C++ components externally” for details.

Use Platform Independent Library Naming

(only for C++ components)

If selected, the platform name is included in the component library and executable name, to allow deployment to mixed architecture clusters.

See “Creating C++ components for multiplatform clusters” for details on this feature.

Prog ID

(only for ActiveX components)

The progid that the component uses in the COM Automation Server Registry.

EAServer Manager does not register the ActiveX component DLL. Before running the component, you must register the DLL with the Windows regsvr32 command or by using the registration feature in your ActiveX development tool.

PowerBuilder Class Name

only for PowerBuilder components

Matches the name of the nonvisual object that implements the component’s methods.

Set by PowerBuilder, defined in the EAServer Component Wizard.

PowerBuilder Library List

only for PowerBuilder components

A list of the PowerBuilder library files that are required to run the object, separated by semicolons. For example:

mylib.pbl;anotherlib.pbl

Set by PowerBuilder, defined in the EAServer Component Wizard.

PowerBuilder Application

only for PowerBuilder components

The name of the PowerBuilder application that contains the NVO that implements the component.

Set by PowerBuilder, defined in the EAServer Component Wizard.


Component properties: Transactions

The Transactions tab configures the component’s transactional properties. Chapter 2, “Understanding Transactions and Component Lifecycles” provides useful background for the transactional properties.

Transaction attribute values

The transaction attribute determines how methods in your component participate in transactions; at the component level, the setting affects all methods. You can also set a transaction attribute for methods within a component (see “Method properties”). Values set at the method level override the component setting.

NoteTransaction attribute in imported EJB components EJB 2.0 or 1.1 components imported from an EJB JAR file have the transaction attribute set for each method. To use the component level setting, set the transaction attribute to Default to Component for each method.

The transaction attribute can have the following values:

NoteEAServer allows only one transaction per component instance A component instance may not execute in two transaction contexts. You cannot set a transaction attribute at the method level that conflicts with the component level setting. For example, you cannot set the component transaction attribute to Mandatory and a method transaction attribute to Requires New. If a method invocation would cause this rule to be violated, the server returns an exception to the client and logs the error in the server log file.

Transaction isolation level

Specifies the isolation level for transactions begun by the component’s methods. This setting can be configured for the component and for individual methods (see “Method properties”). The choices are:

NoteThe transaction isolation level is supported for EJB 1.0 components only.

Automatic demarcation/ deactivation

Applies to components that use a control interface in which the instance activation and deactivation correspond to transaction boundaries. In other words, the option does not apply to EJB components or any omponent that uses the control interface CtsComponents::ObjectControl (the control interface property is “Configuring a control interface”).

For EJB components and components that use the CtsComponents::ObjectControl control interface, this option is ignored; for these compnents, the Stateless option on the Instances tab determines whether the component is deactivated after every method invocation.

When Automatic demarcation/deactivation is enabled, EAServer deactivates the component instance after every method invocation. Your component need not call the completeWork or rollbackWork transaction primitives when this property is enabled. If your component is transactional, calling rollbackWork or throwing the CORBA TRANSACTION_ROLLEDBACK exception aborts the transaction. Setting any other transaction state commits the transaction.

By default, this option is enabled for new components.

NoteIf component is stateful disable Automatic demarcation/deactivation If your component maintains state across method invocations, you must disable the automatic transaction demarcation property. For example, if you read and modify class member fields in response to method invocations, you must disable this option.

Automatic failover

When this option is enabled, client proxies for the component can transparently failover to alternate servers when a server becomes unavailable. This option cannot be enabled unless you have enabled the Automatic demarcation/deactivation option.

Automatic failover requires that your application use a cluster of servers, so that redundant servers are available to run the application’s components. The cluster must include at least one name server and clients must resolve proxy references using naming services. See Chapter 7, “Load Balancing, Failover, and Component Availability,” in the EAServer System Administration Guide for more information.


Component properties: Instances

Properties on the Instances tab configure how instances of the component are created and bound to server-side threads and client-side object references. Table 4-2 describes the settings:

Table 4-2: Instances tab component properties

Property

Description

Concurrency

Enabling this option allows multiple method invocations to occur simultaneously. Concurrent access can decrease the response time of client method invocations. Enable this option for any component that is thread safe.

If this option is disabled, EAServer serializes all method calls to the component.

Concurrency applies to execution of all instances. With concurrency disabled, a call to one instance cannot overlap the execution of another instance.

If a PowerBuilder component is Shared, disable Concurrency. PowerBuilder is thread safe at the session level only.

NoteConcurrency option disabled If the Sharing and Bind Thread options are selected, the Concurrency option is implicitly disabled.

Bind Object

Applies to stateful components only (Automatic Demarcation/Deactivation must be disabled on the Transactions tab or the component must be a stateful session EJB). When this property is enabled, an instance is bound to a client's proxy reference until the client destroys or releases the reference.

If you enable this option, your component must be thread-safe; that is, one instance must be able to execute on multiple threads concurrently. A client may call the proxy from multiple threads, or pass the proxy to another process or component; consequently, there is no guarantee that calls are serialized with Bind Object enabled.

Component instances are destroyed when the client instance reference times out (the time out period is configured on the Instances tab–see “Component properties: Instances”). Instances are not pooled.

Bind Object is most commonly used for storage components, which are used to store a component’s state information in a database. See “Component properties: Persistence” for more information on storage components.

Bind Thread

When this option is enabled, component instances are bound to the creating thread. Enable this option if the component uses thread-local storage. For ActiveX components, this option must be enabled. For other component types, enable the option only if you are sure that your component uses thread-local storage.

If the Bind Thread option is selected, multiple instances may still run concurrently on separate threads. To ensure that only one instance is active at a time, make sure that the Concurrency option is not selected.

When Bind Thread is enabled, instances are pooled if the Pooling option is enabled. The thread is pooled with the instance in this case.

Pooling

When this option is enabled, component instances are always pooled after deactivation. For Java and ActiveX components, you can also configure pooling by implementing interfaces with a canReuse (Java) or canBePooled (ActiveX) method. If you enable the Pooling option in EAServer Manager, your component is always pooled, and these methods are not called. See “Supporting instance pooling in your component” for more information on instance pooling.

Sharing

When this option is enabled, a single, shared instance of the component services all client requests.

A shared component can store data in instance variables. However, if the component’s Concurrency option is also selected, you must add code to synchronize access to instance variables.

If a PowerBuilder component is Shared, disable Concurrency. PowerBuilder is thread safe at the session level only.

NoteSharing setting overrides Pooling setting If you select both Sharing and Pooling, Sharing takes precendence.

Stateless

This option applies only to EJB session Beans and non-EJB components that use the control interface CtsComponents::ObjectControl. For EJB session Beans, the Stateless option is set correctly when the component type is set, and must not be changed. For other component types, the option must be set manually.

External Server

If selected, the component executes externally in the specified server. See “Running components externally”.

External Server/Name

When running the component externally, the name of the external server that hosts the component. The external server must run on the same machine as the server that your application’s clients connect to.

External Server/ Request Timeout

When running the component externally, specifies how long, in seconds, to wait for a response from the external server before returning an error to the client. The default value is set in the server properties for the server where the component is installed.

External Server/ Server Start Timeout

When running the component externally, specifies how long, in seconds, to wait for the external server to start if it is not already running. EAServer returns an error to the client if the external server does not start in the specified time. The default value is set in the server properties for the server where the component is installed.

Transient

Applies to stateful components only. Specifies whether instances can be run on multiple servers in a cluster or survive a server restart. If this option is enabled, the server guarantees that proxy references can only be used within the same server process. For EJB stateful session Beans, this property must be enabled for the standard EJB passivation and activation to occur. It must be disabled if you want to configure a stateful session bean to support failover using the Persistence tab properties (see “Component properties: Persistence”).

Reentrant

Applies to entity components only (including EJB entity Beans). When this option is enabled, an instance is allowed to participate in loopback call sequences, which are call sequences where one of the bean’s methods calls another component which in turn calls a method in the calling bean instance. Most Beans are not implemented to support reentrancy, and you must not enable this option unless the bean developer has verified that the implementation allows it.

LWC

Applies to EJB components only. Enables the EAServer lightweight container (LWC) for intercomponent EJB invocations or calls to EJBs from servlets and JSPs hosted in the same server. For more information, see “Lightweight container” in the EAServer Performance and Tuning Guide.

LWC/ Skeleton Support

If LWC is enabled, the Skeleton Support option enables calls to the component from servlets and JSPs hosted in the same server. Such calls are not supported unless this option is set.


Component properties: Environment

Applies to EJB 2.0 or 1.1 components only. Environment properties allow you to specify read-only site specific data for use by the component. For example, you may have environment properties to specify the name of a logging file, or to tune cache usage, or to specify an email address for the site administrator. See “Configuring environment properties” for more information.


Component properties: EJB Local Refs

Applies to EJB 2.0 components only. EJB local references provide an alias mechanism for the JNDI names used to call other EJB components using local interfaces. The JNDI names used in your compoent must be cataloged on this tab. When deploying the component, a site administrator can map site-specific EJB JNDI names to the references used by your component. To add or edit local references, follow the instructions in “Adding an EJB local reference”, or “Editing an EJB local reference”, respectively.


Component properties: EJB Refs

Applies to EJB 2.0 or 1.1 components only. EJB references provide an alias mechanism for the JNDI names used to create proxies for intercomponent calls to non-EJB components or to EJB components using the EJB remote interface. The JNDI names used in your compoent must be cataloged on this tab. When deploying the component, a site administrator can map site-specific EJB JNDI names to the references used by your component. To add or edit references, follow the instructions in “Adding an EJB reference”, or “Editing an EJB reference”, respectively.


Component properties: Resource Refs

Applies to EJB 2.0 or 1.1 components only. Resource references are used to obtain database connections and JavaMail sessions. The reference allows you to obtain resource factories using JNDI, rather than hard-coding connection parameters in your application. See “Configuring resource references” for more information.


Component properties: Resource Environment Refs

For EJB 2.0 components, resource environment references are logical names applied to objects administered by EAServer.

StepsAdding or editing a resource environment reference

  1. Open the Component Properties dialog box.

  2. “Resource environment references” describes how to add and edit a resource environment reference.


Component properties: Role Refs

Applies to EJB 2.0 or 1.1 components only. Role references are required if you call the isCallerInRole Java method to restrict access. Each reference maps a string used in isCallerInRole calls to a J2EE role that is configured in the package Role Mappings. See “Configuring role references and method permissions” for more information.


Component properties: Resources

Properties on this tab govern the allocation and deallocation of resources required by the component.

For information on tuning the instance pool size properties, see “Instance pooling” in Chapter 3, “Component Tuning,” in the EAServer Performance and Tuning Guide.


Component properties: Persistence

The Persistence tab allows you to specify an EJB entity bean’s primary key and configure settings that allow EAServer to save component state to a database server or using inter-server in-memory replication to support failover in clustered deployments. For more information, see these chapters:


Component properties: Run-As Identity

This tab applies to EJB 2.0 components only. These properties specify the authentication credentials that are used when methods call other components. By default, the client credentials are used. You can specify an alternate credential with these settings:

The Existing Mappings on the Package table displays logical identity names that are mapped to EAServer identities by components in the same package.

To enable use of the run-as identity for EJB component calls to remote servers, you must specify corbaname URLs in the EJB Reference properties for the EJB component that issues the call. For more information, see “Interoperable naming URLs” and “Configuring EJB references”.


Component properties: Run-As Mode

This tab applies to EJB 1.0 components only. These properties specify the user name and password that are used when methods call other EAServer components installed in the same server or server cluster. The setting in the Component Properties dialog box is the default for all methods in the component. You can override the component level setting for individual methods (see “Method properties”).

The choices for Run As Mode are:

Value

Description

Client

Use the client’s user name and password. This is the default setting.

System

Use the system user name and password. The system account effectively belongs to any role, and can execute any method on any component that is installed in the same server or cluster.

Specified

Use the user name and password associated with the identity name specified in the Run-as Identity column.

When Run-As Mode is set to Specified, you must enter a logical entity name, then map the logical identity name to an identity that is defined in the EAServer Manager identities folder. If there are no identities defined, you must close the Component Properties dialog, go to the Identities folder, and create at least one identity to map logical identities to. For more information, see “Configuring identities” in the EAServer Security Programming and Administration Guide.

Mappings specified in the Component Properties dialog are stored as package properties and apply to all other components in the package.


Component properties: Java Classes

For CORBA/Java and EJB components, allows you to define the list of classes that must be custom loaded in addition to the component implementation class. Custom loading allows you to refresh the component installation without restarting the server, and to deploy classes in JAR files without changing the server CLASSPATH environment variable and restarting the server. For more information, see Chapter 30, “Configuring Custom Java Class Lists.”


Component properties: Additional Files

Configures the com.sybase.jaguar.component.files property, which specifies additional files that are included when the component is archived in Jaguar JAR format or replicated with the synchronize feature.

By default, the following files are included when you export packages or synchronize between servers:

NoteJava and C++ stubs are not included by default in the component’s file set. These can be regenerated on the target server after synchronization or installing the archive. If you do not want to regenerate, add the stub files to the list on the Additional Files tab.

Any additional files that are required to run the component must be listed on the Additional Files tab. Use the Additional Files wizard to enter a list of file names, separated by commas. Files may be specified as follows:

Configuring the Additional Files list

When you include additional files, you can either enter the file names individually, or you can use the Additional Files wizard to add multiple files, packages, classes, and directories.

StepsEntering file names individually

  1. Click Add. This opens the Add a File Name to the List dialog box.

  2. Enter the file name and click Ok.

StepsAdding multiple items

  1. Click Additional Files Wizard. This open the Additional Files dialog box. Each item that you add is appended to the list.

  2. To add Java packages or classes:

    1. Click Browse

    2. Choose a *.class file and click Select.

    The class files must be deployed under EAServer’s java/classes directory.

  3. To add files or directories:

    1. Optionally, specify a file filter, such as *.txt.

    2. Optionally, select to use the JAGUAR environment variable.

    3. Click Browse.

    4. Choose a file or directory and click Select.

  4. To add property files from other entities:

    1. Click Browse.

    2. Choose a *.props file from under the Repository directory and click Select.

  5. To add file lists from other entities:

    1. Click Browse.

    2. Choose an entity’s *.files file and click Select.

  6. Click Add Files to Additional Files List.


Component properties: JAXP Support

For EJB 2.0 components, configures the JAXP, DOM, and XSLT parser implementations used in the component. See Chapter 36, “Configuring Java XML Parser Support,” for more information on these properties.


Component properties: Advanced

The Advanced tab allows you to edit component property settings as they are stored in the EAServer configuration repository. You can only delete properties that you have added—you cannot delete default properties, such as the Instance Timeout property.

For information on repository properties, see Appendix B, “Repository Properties Reference,” in the EAServer System Administration Guide.

StepsSetting properties

  1. Look for the property name in the list of properties. If it is displayed, highlight the property and click Modify. Otherwise, click Add.

  2. If adding the property, fill in the Add Property fields as follows:

    1. Enter the property name in the Name field

    2. Enter the value in the Value field.

  3. If modifying a property, edit the displayed value in the Modify Property window.

NoteWhen to use the Advanced tab Though you can use the Advanced tab to set any property prefixed with “com.sybase.jaguar.component”, Sybase recommends that you use this tab to set properties only as specified by the EAServer documentation or by Sybase Technical Support. Most properties can be configured graphically elsewhere in the EAServer Manager user interface.

The following component properties can be configured only from the Advanced tab:

Configuring a control interface

The com.sybase.jaguar.component.control property pecifies the name of the component’s IDL control interface. EAServer calls each control interface method in response to changes in the instance lifecycle. The choices are summarized in this table:

Control Interface

Description

JaguarEJB::EntityBean

For EJB entity Beans.

JaguarEJB::StatefulSessionBean

For EJB stateful session Beans.

JaguarEJB::StatelessSessionBean

For EJB stateless session Beans.

JaguarEJB::ServerBean

A lifecycle model based on the EJB 0.4 specification. This is the default for Java/CORBA components that do not have persistent state (that is, when the Persistence field is None).

CtsComponents::ObjectControl

A CORBA lifecycle model based on the EJB entity bean model. The default for Java/CORBA and C++/CORBA components with persistent state (that is, when the Persistence field is Component Managed).

JaguarCOM::ObjectControl

For ActiveX components.

These interfaces are documented in the generated IDL documentation, which is available in HTML format in the html/ir subdirectory of your EAServer installation. If you use a control interface other than JaguarEJB::ServerBean, EAServer generates the control interface methods in the implementation template when you generate a C++ or Java skeleton.





Copyright © 2005. Sybase Inc. All rights reserved. Running components externally