Appendix A Jaguar 1.1 Java Classes and Interfaces

jaguar.beans.enterprise.CommunicationManager class

Description

package com.sybase.jaguar.beans.enterprise;public class CommunicationManager extends Object

CommunicationManager instantiates stub objects used to invoke Jaguar component methods.

Future versions of the Java Developer's Kit will include a built-in version of this class. The Jaguar implementation is based on a draft version of JavaSoft's Enterprise JavaBeans specification.

Constructors

None. All methods are static.

Methods

• createInstance(Properties) - Create an instance of a server component and return a stub instance that communicates with the server component instance.
• createInstance(String, Class) - Create an instance of a server component and return a stub instance that communicates with the server component instance.
• deregisterDriver(CommunicationDriver) - Remove a previously registered driver from the driver manager's list of installed drivers.
• getDriver(String) - Get the driver instance that recognizes the protocol in the specified URL.
• getDrivers() - Get an enumeration of currently registered drivers.
• registerDriver(CommunicationDriver) - Add a driver to the driver manager's list of installed drivers.

See Also

jaguar.beans.enterprise.Stub interface

CommunicationManager.createInstance(Properties)

Description

Create an instance of a server component and return a stub instance that communicates with the server component instance.

Syntax

public static synchronized Stub createInstance
          ( Properties props) 
          throws EnterpriseBeanException

Parameters

props

A JProperties object initialized to describe the component and the particulars that are required to establish communication with the server. This object must be an initialized JProperties object; passing an instance of any other class will result in an exception.

Return Values

An instance of the stub class for the component specified by URL or null if no installed driver can instantiate a stub for the specified URL.

Cast the returned object to either the generated-stub interface or the generated-stub class. Casting to the interface provides portability to other communication drivers. However, you must cast to the stub class and not the interface if you call Jaguar methods that return row results.

   Note The Jaguar results processing methods cannot be used unless you cast the returned object to the generated stub class (and not the interface). These methods are inherited from either jaguar.stub.jdbc102.JJDBCStub class or jaguar.stub.jdbc11.JJDBCStub class, depending on the JDK version used by your code.

See Also

createInstance(String, Class), getDriver(String), registerDriver(CommunicationDriver), jaguar.beans.enterprise.JProperties class

CommunicationManager.createInstance(String, Class)

Description

Create an instance of a server component and return a stub instance that communicates with the server component instance.

Syntax

public static synchronized Stub createInstance
          ( String URL, Class typeView) 
          throws EnterpriseBeanException

Parameters

URL

A Uniform Resource Locator (URL) of the form:

ejb:protocol[//subprotocol1]

where protocol identifies which CommunicationDriver instance will be used to instantiate the stub class and the rest of the URL indicates a server component and the particulars that are required to establish communication with the server. Each implementation of CommunicationDriver recognizes a different protocol. The comments below describe the URL to use for Jaguar components.

typeView

Not used. Pass as null .

Return Values

An instance of the stub class for the component specified by URL or null if no installed driver can instantiate a stub for the specified URL.

Cast the returned object to either the generated-stub interface or the generated-stub class. Casting to the interface provides portability to other communication drivers. However, you must cast to the stub class and not the interface if you call Jaguar methods that return row results.

   Note The Jaguar results processing methods cannot be used unless you cast the returned object to the generated stub class (and not the interface). These methods are inherited from either jaguar.stub.jdbc102.JJDBCStub class or jaguar.stub.jdbc11.JJDBCStub class, depending on the JDK version used by your code.

Usage

Jaguar component URLs are composed as follows:

ejb:{iiop|iiops|jdbc|jdbc102}//host:port:[jag_tunnel:
  [tport:]][jag_new_connection:]user:pwrd:
  stubpack/srvpack/comp

   Note The component URL must not contain white space. The syntax description above contains a newline to improve readability.

The URL components are:

• ejb - Required to identify the resource as an Enterprise JavaBean.
• iiop|iiops|jdbc|jdbc102 - Identifies the communication protocol, as follows:
  • "iiop" or "jdbc" if the code will run in a Java virtual machine that is compatible with JDK 1.1.
  • "iiops" to specify that the connection should use secure IIOP. The port number (also specified in the URL) determines the security options that are used for the connection. Currently, this option is available only to applets that are running in browsers that support the HTTPS protocol.
  • "jdbc102" if the code will run in a Java virtual machine that is compatible with JDK 1.0.2.
• host - The host name for the Jaguar server.
• port - The port number where the Jaguar server listens for IIOP client connections. The default IIOP port for new servers is 9000. (This is not the same port number used in HTTP URLs. The client-connection port numbers are configured in the server's Listener Objects in Jaguar Manager.)
  The server's IIOP ports are configured in Jaguar Manager, in the IIOP Listeners folder. A server may listen on several ports, each of which accepts connections using different security options. See "Security Configuration" in the Jaguar CTS System Administration Guide for more information.
  
  If you choose a secure port, specify "iiops" as the protocol. If you choose a secure port that requires client-side SSL authentication, users of your program must have an SSL certificate.
  
• jag_tunnel - This option is provided for backward compatibility with Jaguar version 1.1. It has no effect. (The Jaguar 2.0 client runtime uses HTTP tunnelling automatically if it detects that a firewall is forbidding IIOP connections.)
• tport - This option is provided for backward compatibility with Jaguar version 1.1. It has no effect.
• jag_new_connection - Use this keyword if the the stub must use a dedicated connection rather than sharing the connection with other stub instances that connect to the same server. Using dedicated connections may improve the response time of client method calls at the expense of server-side, client-side, and network resources.
• user - The Jaguar user name.
• password - The Jaguar user password.
• stubpack - The dot-separated package name where the component's stub class resides. The stub package name is determined when the stubs are generated--see "Generating Java Stubs" in the Jaguar CTS Programmer's Guide for details.
• srvpack - The name of the Jaguar package that contains the component, as it appears in Jaguar Manager. Package names are not case sensitive. The package must be installed in the server. (Verify that the package is available on the server.)
• comp - The Jaguar component name, as it appears in Jaguar Manager. Component names are not case sensitive. The component must be installed in the srvpack package.

     Note The stub class name must be the same as the component name, as it appears in Jaguar Manager.
  

The example URL below connects to machine "xyz.com," at port 9000, with user "fred," and password "secret." It runs in a JDK 1.1 application (or component) and identifies the component "Stock" in package "Trade." The stub class is OnLineApps.Trade.

ejb:jdbc//xyz.com:9000:fred:secret:OnLineApps.Trade/Trade/Stock

See Also

createInstance(Properties), getDriver(String), registerDriver(CommunicationDriver)

CommunicationManager.deregisterDriver(CommunicationDriver)

Description

Remove a previously registered driver from the driver manager's list of installed drivers.

Syntax

public static synchronized void deregisterDriver
           ( CommunicationDriver driver) 
           throws CommunicationDriverException 

Parameters

driver

The CommunicationDriver instance to be deregistered.

See Also

registerDriver(CommunicationDriver)

CommunicationManager.getDriver(String)

Description

Get the driver instance that recognizes the protocol in the specified URL.

Syntax

public static void getDriver
           ( String URL)
           throws CommunicationDriverException 

Parameters

URL

A URL that identifies an Enterprise JavaBean. See createInstance(String, Class) for details on the URL format.

Return Values

A CommunicationDriver instance that recognizes the specified URL. If no installed driver recognizes the URL, a CommunicationDriverException is thrown.

See Also

createInstance(Properties), registerDriver(CommunicationDriver)

CommunicationManager.getDrivers()

Description

Get an enumeration of currently registered drivers.

Syntax

public static Enumeration getDrivers()
           throws CommunicationDriverException 

Return Values

A java.util.Enumeration object that contains each currently installed CommunicationDriver instance.

See Also

getDriver(String), registerDriver(CommunicationDriver)

CommunicationManager.registerDriver(CommunicationDriver)

Description

Add a driver to the driver manager's list of installed drivers.

Syntax

public static synchronized void registerDriver
           ( CommunicationDriver driver) 
           throws CommunicationDriverException 

Parameters

driver

The CommunicationDriver instance to be registered.

See Also

deregisterDriver(CommunicationDriver)

Copyright © 2000 Sybase, Inc. All rights reserved.