Specifying component properties

Most of the properties listed in this section can be specified in any of the wizards or in the Project painter. Table 3-1 lists the properties in the order they appear in the Application Server Component wizard that you launch from the Target page.

You must define an application server profile before you use a wizard. For more information, see “Creating an application server profile”.

**Table 3-1: Component properties**
Property	Description
Application name, library, and target	By default, the name you use for the application is used for the library and target and as part of the object and component names.
Library search path	The path the target searches for NVOs. Click Browse to add additional libraries to the path.
PowerBuilder object name and description	The name of the NVO in the PowerBuilder library.
Application server component name	The name of the EJB component generated from the NVO. Do not use hyphens in the name of the component or any of its methods.
Application server profile	A predefined profile that specifies the host, port, user name, and password for an application server.
Package name	The name used to generate the default Java package name and JNDI name for the component.
Java package name	The name of the Java package. For an NVO package called “xyz,” the default Java package name is xyz.ejb. Use this property if you want to specify a different name, such as com.mycompany.bank. You must specify a name to deploy the component as an EJB 2.1 Web service.
Package comment	An optional comment that is associated with the package.
Role name list	One or more security role names, entered one on each line. In the Target and PB Object wizards, the role names apply to the component generated by the wizard. In the Project wizard, the role names apply to all the components selected in the wizard. You can associate role names with individual components on the Components page of the Properties dialog in the Project painter. If required, use your application server to map these logical role names to physical roles.
Instance pooling options	Whether an instance of a component is always pooled after each client use, or controlled by the CanBePooled event. See “Controlling the state of a pooled instance”.
Component timeout	How long a component can remain idle before being deactivated. The default, 0, specifies that the component is never automatically deactivated.
Transaction support options	Whether the component supports transactions. See “Transaction support options”.
Stateless session bean	Whether the component is in stateless mode.
Expose user events as methods	Whether to include user-defined events in the component interface.
Expose public instance variables	Whether to generate get and set methods for public instance variables.
Use of unsupported datatypes generates an error	Whether to generate an error at build time if the component uses unsupported datatypes such as system datatypes and the Any datatype. If you choose not to generate errors, any functions or variables that use unsupported datatypes are not available in the component interface.
Perform full rebuild	Whether to perform a full rebuild before deploying to the server to ensure that all objects are synchronized.
Collapse class hierarchy	Whether the methods of ancestor objects are included in the component interface.
Debugging options	Whether the component can be debugged remotely and rebuilt from the User Object painter. These options are for use in test environments only. See “Testing and debugging components”.
Expose component as EJB 2.1 Web service	Whether to expose the component on the server as an EJB 2.1 Web service. The application server must support J2EE 1.4, and you must specify a Java package name. EJB 2.1 Web services do not support the ResultSet return type. You must use array or structure types instead. Method names cannot be overloaded.
Project name and description	The name and optional description of the project used to generate and deploy the component.
Dynamic library options	Whether to consolidate all the libraries in the library list into a single PowerBuilder dynamic library (PBD) file. To ensure that DataWindow™ objects are included in the PBD, select Include Unreferenced Objects.

Creating an application server profile

An application server profile is a named set of parameters stored in your system registry that defines a connection to a particular application server host. Before you use a wizard to create a component, create a profile for the server where the component will be deployed.

Select Tools | Application Server Profile.

The Application Server Profiles dialog displays, listing your configured application server profiles.
Select Add.

The Edit Application Server Profile dialog displays.
Enter the profile name, the TCP host name for the server, the IIOP port number on the server, the login name admin@system, and the password you specified for the server plug-in.
(Optional) Select Test to verify the connection.
Click OK to save your changes and close the dialog box.

The Application Server Profiles dialog displays, with the new profile name listed. The application server profile values are saved in the Registry in HKEY_CURRENT_USER/Software/Sybase/PowerBuilder/10.5/ JaguarServerProfiles.

Transaction support options

Each component has a transaction attribute that indicates how the component participates in transactions. Table 3-2 lists the options.

**Table 3-2: Transaction attribute options**
Transaction type	Description
Not Supported	The component never executes as part of a transaction. If the component is activated by another component that is executing within a transaction, the new instance’s work is performed outside the existing transaction.
Supports Transaction	The component can execute in the context of a transaction, but a transaction is not required to execute the component’s methods. If the component is instantiated directly by a client, the server does not begin a transaction. If component A is instantiated by component B and component B is executing within a transaction, component A executes in the same transaction.
Requires Transaction	The component always executes in a transaction. When the component is instantiated directly by a client, a new transaction begins. If component A is activated by component B and B is executing within a transaction, A executes within the same transaction; if B is not executing in a transaction, A executes in a new transaction.
Requires New Transaction	Whenever the component is instantiated, a new transaction begins. If component A is activated by component B, and B is executing within a transaction, then A begins a new transaction that is unaffected by the outcome of B’s transaction; if B is not executing in a transaction, A executes in a new transaction.
Mandatory	Methods can be invoked only by a client that has an outstanding transaction. Calling this component when there is no outstanding transaction generates a runtime error.
Never	Methods cannot be invoked when there is an outstanding transaction. Calling this component when there is an outstanding transaction generates a runtime error.

The PowerBuilder TransactionServer class supports the following methods:

CreateInstance – (for NVO intercomponent calls) use the two-argument form, and specify the full JNDI name of the target component:
```
TransactionServer ts
getContextService(“TransactionServer”, ts)

// generate and use proxies
pbtest_MyComp comp
ts.createInstance(comp, “pbtest/MyComp”)

// call methods on comp
```
If the target NVO is not in the same EJB-JAR as the calling NVO, your application server’s class loader may not work correctly; you may get a ClassCastException. Consult your application server vendor for help with class-loader issues across EJB-JAR boundaries.
DisableCommit – prevents the current transaction from being committed, because the component’s work has not been completed. The instance remains active after the current method returns.
EnableCommit – do not deactivate the component after the current method invocation; allow the current transaction to be committed if the component instance is deactivated.
IsTransactionAborted – determines whether the current transaction has been aborted.
SetAbort – specifies that the component cannot complete its work for the current transaction and that the transaction should be rolled back. The component instance is deactivated when the method returns.
SetComplete – indicates that the component has completed its work in the current transaction and that, as far as it is concerned, the transaction can be committed and the component instance can be deactivated.

If you are using neither a proxy server nor the TransactionServer.CreateInstance method for NVO intercomponent calls, remove “-djcProxy” from the ejbSourceOptions property value in pb-server-<targetServerName>.xml, and re-run configure. This prevents generating unused code.

Controlling the state of a pooled instance

When you create an application server component that supports instance pooling, that component might need to reset its state after each client has finished using the pooled instance.

To allow you to control the state of a component, the application server triggers one or more of the events shown in Table 3-3 during the life cycle of the component.

**Table 3-3: Component-state events**
Event	PBM code
Activate	PBM_COMPONENT_ACTIVATE
CanBePooled	PBM_COMPONENT_CANBEPOOLED
Deactivate	PBM_COMPONENT_DEACTIVATE

When the component’s pooling option is set to Supported, you might need to script the Activate and Deactivate events to reset the state of the pooled component. This is necessary if the component maintains state in an instance, shared, or global variable.

When the component’s pooling option is set to Not Supported, you can optionally script the CanBePooled event to specify whether a particular component instance should be pooled. If you script the CanBePooled event, you may also need to script the Activate and Deactivate events to reset the state of the pooled component. If you do not script the CanBePooled event, the component instance is not pooled.

The Application Server Component wizards that you launch from the Target and PB Object pages automatically add the Activate and Deactivate events to the NVOs they generate. If you want to script the CanBePooled event, add this event yourself. If you do this, map the event to the correct PBM code.

Constructor and Destructor are fired once When instance pooling is in effect, a component’s Constructor and Destructor events are each fired only once. The Constructor and Destructor events are not fired each time a new client uses the component instance. Therefore, to reset the state of a component instance that is pooled, add logic to the Activate and Deactivate events, instead of to the Constructor and Destructor events.

PowerBuilder to EJB datatype mapping

Table 3-4 lists the PowerBuilder to EJB datatype mappings, which are valid for datatypes passed by value, in and return parameter modes.

The PowerBuilder Application Server Plug-In does not support IDL inout and out parameter modes, because JAX-RPC holder classes are not portable in EJB remote interfaces.

**Table 3-4: PowerBuilder to EJB datatype mappings**
PowerBuilder type	EJB parameter type
Blob	byte[]
Boolean	boolean
Byte See “Byte datatype”.	byte
Char	char – see “Character datatypes”.
Date	java.util.Calendar
DateTime	java.util.Calendar
Decimal	java.math.BigDecimal
Double	double
Integer	short For Java client components that communicate with PowerBuilder server components, the numerical range that this datatype supports is -32768 – 32767.
Long	int For Java client components that communicate with PowerBuilder server components, the numerical range that this datatype supports is -2147483648 – 2147483647.
LongLong	long
Real	float
String	String
Time	java.util.Calendar
MyModule_MyArray[] or MyArray[] (return type only)	MyModule.ejb.MyElement[]
MyModule_MyException or MyException	MyModule.ejb.MyException
MyModule_MyComp or MyComp	MyModule.ejb.MyComp
MyModule_MyStruct or MyStruct	MyModule.ejb.MyStruct
MyModule_MyUnion or MyUnion	MyModule.ejb.MyUnion
MyModule_MyElement[] or MyElement[]	MyModule.ejb.MyElement[]
MyModule_MySequence or MySequence (return type only)	MyModule.ejb.MyElement[]
MyModule_MyElement[n] or MyElement[n]	MyModule.ejb.MyElement[]
ResultSet	java.sql.ResultSet
ResultSets	java.sql.ResultSet[]
XDT_BooleanValue	java.lang.Boolean See “XDT datatypes”.
XDT_CharValue	java.lang.Character See “Character datatypes”.
XDT_ByteValue	java.lang.Byte
XDT_ShortValue	java.lang.Short
XDT_IntValue	java.lang.Int
XDT_LongValue	java.lang.Long
XDT_FloatValue	java.lang.Float
XDT_DoubleValue	java.lang.Double
XDT_DecimalValue	java.math.BigDecimal
XDT_IntegerValue	java.math.BigInteger
XDT_DateValue	java.util.Calendar
XDT_TimeValue	java.util.Calendar
XDT_DateTimeValue	java.util.Calendar

Sybase suggests that you use the PowerBuilder DataStore system object with the ResultSet return type, especially for NVOs running in an application server. For improved performance, use NVO instance variables, and create the DataStore and assign the DataObject in your NVO constructor.

Byte datatype

PowerBuilder version 10.5 introduced a Byte datatype. To use the PowerBuilder Char datatype for backward compatibility, run the following command (once) before deployment:

configure idl-octet-to-pb-char

To switch back to using the PowerBuilder Byte datatype, run the following command (once) before deployment:

configure idl-octet-to-pb-byte

Camel case option

You can modify the default mapping of CORBA IDL identifiers to EJB identifiers to use Java naming conventions. This is called the “camel case” deployment option. When using this option, IDL operation and parameter names, such abc_xyz, map to abcXyz. IDL interfaces, sequence, structure, and union type names, such as abc_xyz, map to AbcXyz. These mappings are not applied to exception and structure field names. By default, the camel case option is disabled.

To enable the camel case option:

configure camel-case-on

To disable the camel case option:

configure camel-case-off

If you plan to expose components as Web services, enable the camel case option; otherwise, you may have problems with the JAX-RPC identifier mapping rules. See Chapter 20, “Appendix: Mapping of XML Names” in the JAX-RPC 1.1 specification, which you can download from Java Technology and XML Downloads.

Character datatypes

Only characters in the ISO 8859-1 character set can be used for in and return parameter modes. To propagate other characters, use the String datatype.

The char and java.lang.Character datatypes have no defined XML schema mappings for EJB Web services, so you cannot use these as a parameter types or structure field types if you intend to expose a component as a Web service. Use the String datatype instead.

DataStore system object

Sybase recommends that you use the PowerBuilder DataStore system object with the ResultSet return type, especially for NVOs running in an application server. For improved performance, use NVO instance variables, and create the DataStore and assign the DataObject in your NVO constructor.

ResultSet datatype

If you intend to expose a component as a Web service, do not use the ResultSet datatype, because java.sql.ResultSet is not portable in EJB Web service endpoint interfaces. You can use arrays (IDL sequences) of structures instead, Java arrays or PowerBuilder variable-sized arrays. The EJB return type java.sql.ResultSet maps to a complex XML schema element that contains result set data and the schema for the result set. The content of the nested XML element is mapped according to the SQL/XML ANSI standard; for example:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
   targetNamespace="jdbc.wst.sybase.com">
  <import namespace="http://schemas.xmlsoap.org/soap/encoding/" />
    <complexType name="DataReturn">
    <sequence>
       <element name="XML" nillable="true" type="xsd:string" />
       <element name="updateCount" type="xsd:int" />
       <element name="DTD" nillable="true" type="xsd:string" />
       <element name="schema" nillable="true" type="xsd:string" />
    </sequence>
   </complexType>
</schema>

Using IDL parameter modes inout and out with TabularResults::ResultSet is not supported for components that are exposed as Web services. You may find that using arrays (IDL sequences) of structures instead of ResultSets simplifies the coding of Web service client applications, and this technique is portable across all application servers. When writing PowerBuilder NVO methods, which do not permit the use of arrays as method return types, define a row structure to represent a result row, and a table structure containing an array of row structures to represent a ResultSet.

XDT datatypes

To obtain the PowerBuilder XDT_* datatypes to use as PowerBuilder structure field types or component parameter types, use the EAServer Proxy wizard or the Application Server Proxy wizard in the PowerBuilder IDE to generate proxies for the XDT package. Each of the XDT_* datatypes contains a value field and an isNull field. You must set isNull to true if you want to indicate null values.