Working with shared and service components
When you create an EAServer component
in PowerBuilder, the wizard offers you a choice of creating a standard,
shared, or service component.
About shared components
How EAServer manages program variable
space
The EAServer architecture
is component-oriented. Each component maintains its own state. When
a single client instantiates several PowerBuilder objects on the
server, EAServer maintains program
variable space for the objects separately. Each PowerBuilder user
object running in EAServer has
its own copy of the global and shared variables. The PowerBuilder
objects share no common state. They can communicate only through
methods, EAServer shared components,
server files, and databases.
To allow clients to share state information, EAServer provides support for shared
components. Shared components allow multiple clients to share the same
component instance.
EAServer Manager and the Management Console In EAServer 5.x, you use EAServer Manager to manage properties
in EAServer. In EAServer 6.x, you use the EAServer Manager plug-in the Sybase Management
Console.
Marking a component as shared in a PowerBuilder wizard is
equivalent to marking it as shared on the General page of the component’s
properties in the Management Console or the Instances page in EAServer Manager. Only a single
instance of the component can be instantiated in EAServer.
Clients (and other server components) access a shared component
as if it were any other kind of component.
Benefits of using EAServer shared components
Shared components allow you to:
- Provide convenient access to common data that would otherwise
need to be retrieved separately by each client connection - Reduce the number of database accesses, allowing
the database server to be available for other processing
EAServer shared components
versus PowerBuilder shared objects
EAServer shared components
offer many of the same benefits as PowerBuilder shared objects.
PowerBuilder components that you deploy to EAServer can
act as clients to EAServer shared
components, as well as to PowerBuilder shared objects. EAServer shared components can also
be accessed by components and clients that are not implemented in
PowerBuilder.
However, EAServer does not
treat PowerBuilder shared objects as if they were EAServer shared components. Therefore,
the functions used to manipulate PowerBuilder shared objects (SharedObjectRegister, SharedObjectGet,
and so forth) do not work with EAServer shared
components. If you try to call one of these functions inside a PowerBuilder
component running in EAServer,
the request will fail.
About service components
A service component performs background processing for EAServer clients and other EAServer components. EAServer loads service components
at server start-up time.
When you mark a component as a service component in one of
the PowerBuilder wizards, PowerBuilder installs the component as
a service in EAServer at deployment
time.
Shared or not shared
When you create a service component, the wizard marks the
component as shared. If you want more than one instance of a service
component, you can change that setting in the Project painter. Select
the number of instances you want in the Create Instances spin control
on the Components page of the EAServer Component
Generator property sheet in the Project painter. Notice that when
you change the number of instances to a number greater than one, the
Concurrency and Automatic Demarcation/Deactivation are
checked. This is to ensure that the component does not encounter
threading issues in EAServer.
For more information, see “Threading issues and component
types”.
Functions for service components
The PowerBuilder wizards include three additional functions
for a service component. These functions are defined in the CTSServices::GenericServices interface
and allow you to control the behavior of background processes associated
with the service:
- Start EAServer calls the Start function
after the service component has been loaded. You can add logic to
this function to perform start-up initialization for the service. - Run EAServer calls the Run function
after the first invocation of the Start function
returns. The Run function allows you to perform
repetitive tasks as a background process. The Run function
must periodically suspend its own execution by calling the JagSleep C
function. The JagSleep function frees the CPU
to perform other tasks. To use the JagSleep function,
declare an external function for JagSleep in
PowerBuilder. Here is the syntax to use for the function declaration:1subroutine JagSleep (Long seconds) LIBRARY<br> "libjdispatch.dll" - Stop This function allows you to stop the execution of the background process
coded in the Run function. You can implement
a service-manager client for your service that calls Stop, Start,
and Run so that the service can be restarted
without restarting EAServer. The
script for the Stop function can also clean up
any resources that were allocated in the Start function.
Threading issues and component types
Each instance of a PowerBuilder component executes in its
own session, and each session can support only one thread of execution.
Therefore a single PowerBuilder component instance cannot simultaneously
execute multiple client requests. However, multiple instances of
the same component can each execute a separate client request. When
you create a component, PowerBuilder sets default values for several
properties that affect the way threads are handled in EAServer.
Using the Thread Manager You can also use the EAServer Thread
Manager to develop more robust services. See “Using the EAServer Thread Manager”.
Concurrency property
The Concurrency property determines
whether multiple instances of a component can be created to handle
multiple client requests. Checking the Concurrency check box in
the wizard or the Project painter sets the com.sybase.jaguar.component.thread.safe
property to TRUE.
Standard components For standard components, you can improve performance by allowing
multiple instances of a component to handle client requests. The
default setting for the concurrency property for standard components
is checked, but you can change the setting if you want only one instance
of a given component.
Shared components For shared components, only one instance of the component
should be active at any time and therefore only one thread can be executed.
The Concurrency check box is disabled and not checked for shared components.
Service components Although service components are usually treated as shared
components, you can choose to create more than one instance of a service
component to improve performance and scalability. There are three options
on the Components page that interact for service components: Concurrency,
Automatic Demarcation/Deactivation, and Create Instances
(the Create Instances option can be changed only for service components).
When you change the Create Instances option to 2 or more,
the Concurrency check box and the Automatic Demarcation/Deactivation
check box become checked. Multiple instances of the service component
can be created if necessary, and are deactivated after each method
call. If you clear the Automatic Demarcation/Deactivation
check box, so that you need to explicitly deactivate component instances,
the Create Instances check box is reset to 1 and the Concurrency
check box is cleared.
bind.thread, sharing, and tx_vote properties
There are three other component properties that affect the
handling of threads in EAServer:
sharing, tx_vote, and bind.thread.
Bind Object property not used An additional
property, bind.object, enables client threads to execute in a single instance
but also supports creation of multiple instances. This property cannot be
used for PowerBuilder components and is always set to FALSE.
When the bind.thread property is set
to TRUE, a method on a component instance must
execute on the same thread that created the instance. This property
must be set to TRUE if you are using live editing
to build your component. It should be set to FALSE for
components that are deployed to UNIX servers to improve scalability.
The sharing property identifies whether
or not the component is shared. It is set to FALSE when
you select Standard in the wizard and to TRUE when
you select Shared or Service. The only way this property can be
changed in PowerBuilder is by changing the Create Instances setting
on the Components tab page for service components in the Project
painter. If either the sharing or thread.safe property is set to TRUE,
the other must be set to FALSE.
A component that can remain active between consecutive method
invocations is called a stateful component. A component that is
deactivated after each method call and that supports instance pooling
is said to be a stateless component. Typically, an application built
with stateless components offers the greatest scalability. The tx_vote
property determines whether the component is deactivated after every
method call. It is set to FALSE (stateless) if
you check the Automatic demarcation/deactivation check
box in the wizard or select more than one instance on the Component
page in the Project painter; otherwise it is set to TRUE (stateful).
You can have only one instance of a stateful service object.
Table 23-1 summarizes
the default setting for each type of component and shows which can
be changed.
| Component | bind.thread | sharing | thread.safe | tx_vote |
|---|---|---|---|---|
| Standard | FALSE, mutable | FALSE, immutable | TRUE, mutable | FALSE, mutable |
| Shared | FALSE, mutable | TRUE, immutable | FALSE, immutable | FALSE, mutable |
| Service (single instance) | FALSE, mutable | TRUE, immutable | FALSE, mutable | FALSE, mutable |
| Service (multiple instances) | FALSE, mutable | FALSE, immutable | TRUE, mutable | FALSE, mutable
If changed to TRUE, number of instances |
If you deploy a service component for which bind.thread, thread.safe,
and sharing are set to TRUE, EAServer disables the thread.safe
property automatically at runtime.
Using the EAServer Thread Manager
The Thread Manager is a built-in EAServer component
that allows you to run EAServer component
instances in threads that execute independently of client method
invocations. You can use threads spawned by the Thread Manager to perform
any processing that must occur asynchronously with respect to user interaction.
For example, you might have a component method that begins
a lengthy file indexing operation. The method could call the Thread
Manager to start the processing in a new thread, then return immediately.
Since each instance of a PowerBuilder component executes in
its own session, and each session can support only one thread of
execution, you cannot develop a service that can be stopped or refreshed
without using the Thread Manager. In the service’s start or run method,
spawn threads that do the service’s processing. In the
service’s stop method, call the Thread
Manager stop method to halt the threads.
For a more complete description of the Thread Manager, see
the EAServer documentation.