Invoking component methods
Once a connection to EAServer has
been established and a proxy object or objects created, the client
application can begin using the server components.
Invoking a component method
To invoke a method on most component types, you need to execute
the PowerScript statements required to perform these operations:
- Use the CreateInstance method
to create an instance of the component. - Invoke the method.
You use a different technique to invoke EJB component methods.
See “Invoking an EJB component
method”.
Example 1 This script instantiates a component on the server and invokes
a component method. In this example, the CreateInstance method
does not specify a package; therefore, EAServer uses
the default package specified in the Application property of the
Connection object:
|
1 |
// Global variable:<br />// connection myconnect<br /><br />uo_customer iuo_customer<br />string ls_custid<br />long ll_rc<br /><br />ls_custid = Trim(sle_custid.text)<br />ll_rc = myconnect.CreateInstance(iuo_customer)<br />if ll_rc <> 0 then <br /> MessageBox("CreateInstance failed", ll_rc) |
|
1 |
return 999<br />end if<br />if iuo_customer.retrieve_balance(ls_custid) != 1 then<br /> MessageBox("Error", "Retrieve failed!")<br />end if |
Example 2 This script instantiates a component on the server and assigns
the object reference to a variable whose datatype is an ancestor
of the class for the component. The second argument to the CreateInstance function
specifies the class name for the component as well as the EAServer package name:
|
1 |
// Global variable:<br />// connection myconnect<br /><br />uo_person lnv_object<br />string ls_custid<br />long ll_rc<br /><br />ls_custid = Trim(sle_custid.text)<br />ll_rc = myconnect.CreateInstance(lnv_object, &<br /> "PB_pkg_1/uo_customer")<br />if ll_rc <> 0 then <br /> MessageBox("CreateInstance failed", ll_rc) |
|
1 |
return 999<br />end if<br />if iuo_customer.retrieve_balance(ls_custid) != 1 then<br /> MessageBox("Error", "Retrieve failed!")<br />end if |
Invoking a local instance By default, the TransactionServer CreateInstance method
invokes the EAServer name service
to create proxies. Proxies for remote components might be returned
by the name service rather than an instance that is running locally.
To guarantee that a locally installed instance is used, specify
the component name as “local:package/component“,
where package is the package name and component is
the component name. The call fails if the component is not installed
in the same server.
Invoking an EJB component method
To
invoke an EJB component method, you need to execute the PowerScript statements
required to perform these operations:
- Use the Lookup function to access the component’s
home interface. - Invoke the method on the interface to create or
find an instance of the component and get a reference to the component’s
remote interface. - Invoke the business methods on the remote interface.
Does not apply to EJBConnection methods This section applies to client applications that use an EAServer proxy object and PowerScript
functions. For information about invoking EJB methods in client
applications that use an EJB client proxy and EJBConnection methods, see Chapter 29, “Building an EJB client .”
Specifying the home interface name
PowerBuilder provides an optional third argument to the Lookup function
to specify the name of the home interface. EJB components have a
property in EAServer called com.sybase.jaguar.component.home.ids.
You do not need to specify the third argument to the Lookup function
if the home.ids property looks like this:
|
1 |
IDL:<i>PackageName</i>/<i>ComponentName</i>Home:1.0 |
For example:
|
1 |
IDL:vacation/TripFinderHome:1.0 |
In most cases, however, the home.ids property uses the java
package naming scheme and you should use the third argument to make
sure that the EJB home interface can be located. The string that
you specify for this argument must match the component’s
com.sybase.jaguar.component.home.ids property without the leading IDL: and
trailing :1.0.
For example, suppose the home.ids property is this:
|
1 |
IDL:com/myproj/myejbs/TripFindHome:1.0 |
Your Lookup function call should look like
this::
|
1 |
myconn.lookup(myTripFindHome,"MyEJBs/TripFindHome", &<br /> "com/myproj/myejbs/TripFinderHome") |
Alternatively, you can use the fully-qualified Java class
name of the home interface specified in dot notation. For example:
|
1 |
ts.lookup(MyCartHome, "MyEJBs/TripFindHome", & "com.myproj.myejbs.TripFinderHome") |
Lookup is case sensitive Lookup in EAServer is
case sensitive. Make sure that the case in the string you specify
for the arguments to the Lookup function matches
the case in the home.ids property.
Creating or finding an instance of an EJB
EAServer supports three
types of EJBs–session beans, entity beans, and message-driven
beans.
A session bean is created in response
to a client request. A client usually has exclusive use of the session
bean for the duration of that client session.
An entity bean represents persistent information stored in
a database. A client uses an entity bean concurrently with other
clients. Since an entity bean persists beyond the lifetime of the
client, you must use a primary key class name to identify or find a
preexisting component, if the bean has already been created.
A message-driven bean is similar to a stateless session
bean, but it responds only to JMS messages and has no direct client
interface.
The following examples assume that an EJB component that provides e-commerce
shopping cart functionality is running on EAServer.
This component is called Cart and is included in a package called
Shopping.
Example 1 This script instantiates the Cart component and invokes several component
methods. In this example, the second argument to the Lookup method
specifies the component name as well as the EAServer package
name:
|
1 |
//Instance variable:<br />//Connection myconnect<br /><br />CartHome MyCartHome // EJB's home interface<br />Cart MyShoppingCart // EJB's remote interface<br />long ll_result<br /><br />//Get the home interface<br />ll_result = &<br />myconnect.Lookup(MyCartHome, "Shopping/Cart", &<br /> "com.sybase.shopping.Cart")<br /><br />//Get a reference to Cart component's business logic<br />TRY<br /> MyShoppingCart = MyCartHome.Create()<br />CATCH (ctscomponents_createexception ce)<br /> MessageBox("Create exception", ce.getmessage())<br /> // handle exception<br />END TRY<br /><br />//Use the shopping cart<br />MyShoppingCart.AddItem(66)<br />MyShoppingCart.Purchase() |
Example 2 If the Cart EJB component is defined as an entity bean, then
the script must use the findByPrimaryKey method
to find and reference a preexisting or persistent component if one
exists:
|
1 |
//Instance variable:<br />//Connection myconnect<br /><br />CartHome MyCartHome // EJB's home interface<br />Cart MyCart // EJB's remote interface<br />long ll_result<br /><br />//Get the home interface<br />ll_result = &<br />myconnect.Lookup(MyCartHome, "Shopping/Cart", &<br /> "com.sybase.shopping.Cart")<br /><br />//Get a reference to Cart from a previous session<br />TRY<br /> MyCart = MyCartHome.findByPrimaryKey("MYkey")<br />CATCH ( ctscomponents_finderexception fe )<br /> MessageBox("Finder exception", &<br /> fe.getmessage())<br /> // handle exception<br />END TRY<br />//Use the shopping cart<br />MyCart.AddItem(66)<br />MyCart.Purchase() |
Restrictions
PowerBuilder clients to EJB objects act as CORBA clients,
which means that they do not have the full capabilities of Java
clients. Java clients can use methods inherited from the javax.ejb.EJBObject
interface.
For example, a Java client can obtain a handle for a remote
interface instance. The handle is a binary encoding of the session
state between the client and the bean. The client can obtain a handle,
save it to disk or mail it to another location, then reestablish
the session at a later time. PowerBuilder clients can obtain similar
functionality using the Object_To_String and String_To_Object functions
of the JaguarORB object.
Handling exceptions
The remote interface of an EJB component can indicate errors
or warnings. Standard exceptions thrown by the EJB component are
mapped to CORBA system exceptions. The EJB component can also throw
user exceptions. For information about handling exceptions thrown
by EAServer components, see “Handling errors “.
For information about calling an EJB component from a PowerBuilder component
in EAServer, see “Accessing an EJB component”.
Destroying instances
Destroying the proxy object instance
After you have finished using an EAServer component,
you can explicitly destroy the EAServer proxy
object by using the DESTROY statement, or you can
let PowerBuilder’s garbage collection facility clear the
object out of memory for you automatically. In either case, the
destruction of the client-side proxy object has no effect on the
lifecycle of the server component. Destruction of the server component
is handled by EAServer.
Deactivating the component instance
If the Automatic Demarcation/Deactivation setting
is disabled for a component, and you close the client application
while the component is still bound to the client (the component
did not call SetComplete or SetAbort),
the component is not deactivated. To ensure
that the component instance is deactivated, you can do one of the
following things:
- In the Close event of the
client application, invoke a method of the server component that
deactivates the component (by calling SetComplete or SetAbort). - Set the Timeout property for the component to a
value other than 0. If the component’s Timeout property
is set to 0, the component will never time out.