ibi.broker.api.cci
Class CasterConnection

java.lang.Object
  ibi.broker.api.cci.CasterConnection

All Implemented Interfaces:

javax.resource.cci.Connection

public class CasterConnection
extends java.lang.Object
implements javax.resource.cci.Connection

 The ReportCaster API makes use of the Java Connection Architecture (JCA) to integrate
 client application components with the ReportCaster Repository and Distribution Server.
 An integral part of the J2EE, JCA uses EIS-specific resource adapters that facilitate 
 connectivity between the application client, the application server, and the ReportCaster
 Repository/Distribution Server.  

 The system constructs a standardized connection contract, transaction contract, and 
 security contract to connect the application servers to EIS (Enterprise Information Systems). 

 The connection contract uses the Connection Manager to manage the pool of connections made 
 available within the J2EE application server environment. The transaction contract and security
 contract use the Transaction Manager and Security Manager, respectively, to manage their 
 elements. Many of the classes and interfaces involved in this part of the EIS access protocol 
 are transparent to the J2EE application server and are stored under the javax.resource.spi package. 

 The application contract is encapsulated by the CCI (Common Client Interface) and connects
 application clients to the underlying EIS. The interfaces that ReportCaster overrides and extends
 in this process are found in javax.resources.cci. ReportCaster implements most of these interfaces
 within the ibi.broker.api.cci package.

 Arbitrary application clients (which could be one of the various kinds of EJB components, such as
 a session Bean or a message driven Bean, JSP, servlet, applet, or Java application) seeking 
 authenticated access to data within the ReportCaster Repository can use ReportCaster's 
 implementation of the CCI to accomplish this task.

 There are two basic modes through which an application client can access or connect to the
 ReportCaster Distribution Server and Repository: 
 

 
Non-Managed Mode. A standalone client application component uses the 
 resource adapter to access the ReportCaster Repository and Distribution Server.
 
Managed Mode. The client application component and the resource adapter are
 deployed within a J2EE application server container, and the application server then manages 
 access to the underlying EIS. 


 To access the repository in either scenario, the client component must possess the 
 application-level handle to the connection object, which is represented by the 
 CasterConnection class. The CasterConnection instance does not 
 represent the actual physical connection to the repository (that is, the 
 ManagedConnection object) but is the handle to the underlying instance used
 by the client application component uses to access the ReportCaster Repository and 
 Distribution Server.  
 

 There are two distinct differences between the connection modalities of the non-managed case
 verses the managed case. In the non-managed case, the connection object is obtained directly
 from the CasterConnectionFactory, without any connection pooling taking place 
 on the application server level. In the managed case, you may have multiple clients interacting
 with multiple EISs. Connection pooling is required to manage connection objects. The client 
 calls to the CasterConnectionFactory are routed, using the resource adapter, to the Connection
 Manager to obtain the CasterConnection object.
 

 
 ReportCaster (or an external application client) looks up the resource adapter connection factory,
 CasterConnectionFactory.
 
 CasterConnectionFactory delegates the request for a connection to 
 the resource adapter's default ConnectionManager instance. 
 
The ConnectionManager either retrieves an existing connection from the connection pool,
 or it calls CasterManagedConnectionFactory to create a new physical connection
 to the repository, which is represented by a ManagedConnection object. 
 This is accomplished using the createManagedConnection.
 
 To create a new ManagedConnection instance, the CasterManagedConnectionFactory
 uses the security information obtained from the Subject object, any ConnectionRequestInfo,
 and its configured set of properties, such as server name and port number.
 
 The ConnectionManager instance calls the ManagedConnection.getConnection() 
 to get the application-level connection handle (CasterConnection object). Calling the getConnection 
 method does not necessarily create a new physical connection to the repository. The call produces a
 temporary handle that is used by the application client to access the underlying physical connection, 
 which itself is represented by a ManagedConnection instance.
 
 ReportCaster (or the application client) returns the connection handle to the 
 CasterConnectionFactory by calling CasterConnection.close().
 
The CasterConnectionFactory returns the connection to the 
 application client component that initiated the connection request.
 
 

 
 The application assembler or component provider specifies connection factory requirements for an
 application component using a deployment descriptor mechanism. For example, a Bean provider 
 specifies the following elements in the deployment descriptor for a connection factory reference:
 res-ref-name: jca/ReportCaster
 res-type: javax.resource.cci.ConnectionFactory
 res-auth: Application
 Note that the connection factory reference is part of the deployment descriptor for EJB components
 and not the resource adapter. 
 
 During resource adapter deployment, the deployer sets the server name and port number for the
 resource adapter. The application server uses a configured resource adapter to create physical connections to the underlying ReportCaster Repository. 
 
 The application component looks up a connection factory instance in the component's environment
 using the JNDI interface. The JNDI name passed in the method NamingContext.lookup is the same as that
 specified in the res-ref-name element of the deployment descriptor. The JNDI lookup results in a 
 connection factory instance of type java.resource.cci.ConnectionFactory, as specified in the res-type
 element:
 // obtain the initial JNDI Naming context
 Context initctx = new InitialContext();
 // perform JNDI lookup to obtain the connection factory
 javax.resource.cci.ConnectionFactory cxf =
 (javax.resource.cci.ConnectionFactory)
 initctx.lookup("java:comp/env/jca/ReportCaster");
 
 The application component invokes the getConnection method on the connection factory to get an EIS 
 connection. The returned connection instance represents an application-level handle to an underlying 
 physical connection. An application component obtains multiple connections by calling the *
 getConnection method on the connection factory multiple times. 
 javax.resource.cci.Connection cx = cxf.getConnection();
 
The application component uses the returned connection to access the underlying ReportCaster 
 Repository using the resource adapter. Note that the JNDI context of an accessing application is 
 available to a resource adapter using the application thread that uses its connection object.
 
 After the component finishes the connection, it closes the connection using the close method 
 on the Connection interface. 
 cx.close();
 
 If an application component fails to close an allocated connection after its use, it is 
 considered an unused connection. The application server manages the clean up of unused connections. 
 When a container terminates a component instance, the container cleans up all connections used by 
 that component instance.
 
 
 

 The following sample code is taken from the samples packaged with the product.  

 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++      
 +  Copyright (c) 2004 Information Builders, Inc. All  Rights Reserved.     +      
 +                                                                          +      
 +  Information Builders offers sample API programs as a heuristic device.  +      
 +  They are not intended, as is, for production use. Licensed users are    +      
 +  welcome to alter and extend these samples and deploy them in other      +      
 +  environments, or alternate configurations, as they see fit.             +      
 +  Information Builders will support the documented functionality of       +      
 +  its API classes and methods. However, Information Builders is not       +      
 +  responsible for functionality or behavior of products built with        +      
 +  its API unless the documented behavior of its discrete classes and      +      
 +  methods is different than the actual results.                           +      
 +                                                                          +      
 +  Redistributions of IBI source code and documentation must be within     +      
 +  the scope of the Information Builders Software License Agreement.       +      
 +                                                                          +      
 + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++   

 package ibi.broker.api.samples;

import ibi.broker.api.CasterManagedConnectionFactory;
import ibi.broker.api.cci.CasterConnection;
import ibi.broker.api.cci.CasterConnectionFactory;
import ibi.broker.api.cci.PasswordCredential;

import java.util.ResourceBundle;

import javax.resource.cci.ConnectionSpec;

public class Util 
{
        public static CasterConnection createCasterConnection() throws Exception
        {
                ResourceBundle bundle = null;
                String host = "localhost";
                String port = "8200";
                String user = "admin";
                String password = "";

                try
                {
                        bundle = ResourceBundle.getBundle("ibi.broker.api.samples.samples");
                        host = bundle.getString("host");
                        port = bundle.getString("port");
                        user = bundle.getString("user");
                        password = bundle.getString("password");
                        
                }
                catch(Exception ex){}
                CasterManagedConnectionFactory managedConnectionFactory = new CasterManagedConnectionFactory();
                managedConnectionFactory.setServerName(host);
                managedConnectionFactory.setPortNumber(port);
                CasterConnectionFactory connectionFactory = (CasterConnectionFactory)managedConnectionFactory.createConnectionFactory();
                ConnectionSpec credential = new PasswordCredential(user, password.toCharArray());
                return ((CasterConnection)connectionFactory.getConnection(credential));
        }
        

}

Version:

5.3

Constructor Summary

CasterConnection(javax.resource.spi.ManagedConnection mc, javax.resource.spi.ConnectionRequestInfo connInfo)
Constructor for CasterConnection.

Method Summary

void	close() Closes this connection to the EIS (for example, ReportCaster Repository).
javax.resource.cci.Interaction	createInteraction() This method is currently not available for use within the API.
AddressBookManager	getAddressBookManager() Obtains an instance of ibi.broker.api.cci.AddressBookManager that is to be used in conjunction with this connection instance.
ibi.broker.api.cci.AnnotationManager	getAnnotationManager()
ibi.broker.api.data.preference.application.ApplicationPreference	getApplicationPreference()
ConfigManager	getConfigManager() Obtains an instance of ibi.broker.api.cci.ConfigManager that is to be used in conjunction with this connection instance.
ConsoleManager	getConsoleManager() Obtains an instance of ibi.broker.api.cci.ConsoleManager that is to be used in conjunction with this connection instance.
ibi.broker.system.dserver.DserverManager	getDserverManager()
LibraryAccessManager	getLibraryAccessManager()
LibraryContentManager	getLibraryContentManager() Obtains an instance of ibi.broker.api.cci.LibraryContentManager that is to be used in conjunction with this connection instance.
javax.resource.cci.LocalTransaction	getLocalTransaction() This method is currently not available for use within the API.
LogManager	getLogManager() Obtains an instance of ibi.broker.api.cci.LogManager that is to be used in conjunction with this connection instance.
java.io.PrintWriter	getLogWriter()
javax.resource.cci.ConnectionMetaData	getMetaData() Obtains information about the active connection to the ReportCaster repository, which is represented by this instance of CasterConnection.
ibi.broker.system.mre.CASTER_MREManager	getMrManager(java.lang.String owner)
javax.resource.cci.ResultSetInfo	getResultSetInfo() This method is currently not available for use within the API.
ScheduleManager	getScheduleManager() Obtains an instance of ibi.broker.api.cci.ScheduleManager that is to be used in conjunction with this connection instance.
protected ibi.broker.security.CasterSecurityManager	getSecurityManager() Obtains the Security Manager that is being used in conjunction with this connection instance.
java.lang.String	getSecurityToken()
User	getUser() Obtain the username of the current ReportCaster user who is accessing this CasterConnection instance.
UserManager	getUserManager() Obtains an instance of ibi.broker.api.cci.UserManager that is to be used in conjunction with this connection instance.
void	setApplicationPreference(ibi.broker.api.data.preference.application.ApplicationPreference applicationPreference)
void	setLogWriter(java.io.PrintWriter logWriter)
void	setMrRole(java.lang.String mrRole)
protected void	setSecurityManager(ibi.broker.security.CasterSecurityManager securityManager) Specifies the Security Manager for use with this CasterConnection instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CasterConnection

public CasterConnection(javax.resource.spi.ManagedConnection mc,
                        javax.resource.spi.ConnectionRequestInfo connInfo)

Constructor for CasterConnection. This constructor takes an instance of ManagedConnection and returns the connection handle to the ReportCaster Repository.

Method Detail

createInteraction

public javax.resource.cci.Interaction createInteraction()
                                                 throws javax.resource.ResourceException

This method is currently not available for use within the API.

Specified by:

createInteraction in interface javax.resource.cci.Connection

Returns:

Always return null.

Throws:

javax.resource.ResourceException

See Also:

Connection.createInteraction()

getLocalTransaction

public javax.resource.cci.LocalTransaction getLocalTransaction()
                                                        throws javax.resource.ResourceException

This method is currently not available for use within the API.

Specified by:

getLocalTransaction in interface javax.resource.cci.Connection

Returns:

Always return null;

Throws:

javax.resource.ResourceException

See Also:

Connection.getLocalTransaction()

getMetaData

public javax.resource.cci.ConnectionMetaData getMetaData()
                                                  throws javax.resource.ResourceException

Obtains information about the active connection to the ReportCaster repository, which is represented by this instance of CasterConnection. The information returned is from the CasterConnectionMetaData class and includes the version of ReportCaster and the username of the currently authenticated user who is accessing the repository.

Specified by:

getMetaData in interface javax.resource.cci.Connection

Returns:

CasterConnectionMetaData instance representing information about the EIS instance.

Throws:

javax.resource.ResourceException - Failed to get information about the connected EIS instance. Error can be from the resource adapter, EIS-specific, or communication related.

See Also:

Connection.getMetaData()

getResultSetInfo

public javax.resource.cci.ResultSetInfo getResultSetInfo()
                                                  throws javax.resource.ResourceException

This method is currently not available for use within the API.

Specified by:

getResultSetInfo in interface javax.resource.cci.Connection

Returns:

null Always returns null.

Throws:

javax.resource.ResourceException

See Also:

Connection.getResultSetInfo()

close

public void close()
           throws javax.resource.ResourceException

Closes this connection to the EIS (for example, ReportCaster Repository).

Specified by:

close in interface javax.resource.cci.Connection

Throws:

javax.resource.ResourceException

See Also:

Connection.close()

setSecurityManager

protected void setSecurityManager(ibi.broker.security.CasterSecurityManager securityManager)

Specifies the Security Manager for use with this CasterConnection instance.

Parameters:

securityManager - ReportCaster's built in Security Manager.

getSecurityManager

protected ibi.broker.security.CasterSecurityManager getSecurityManager()

Obtains the Security Manager that is being used in conjunction with this connection instance.

Returns:

ibi.broker.security.CasterSecurityManager

getAddressBookManager

public AddressBookManager getAddressBookManager()

Obtains an instance of ibi.broker.api.cci.AddressBookManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.AddressBookManager

getLibraryAccessManager

public LibraryAccessManager getLibraryAccessManager()

getScheduleManager

public ScheduleManager getScheduleManager()

Obtains an instance of ibi.broker.api.cci.ScheduleManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.ScheduleManager

getConsoleManager

public ConsoleManager getConsoleManager()

Obtains an instance of ibi.broker.api.cci.ConsoleManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.ConsoleManager

getDserverManager

public ibi.broker.system.dserver.DserverManager getDserverManager()

getLogManager

public LogManager getLogManager()

Obtains an instance of ibi.broker.api.cci.LogManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.LogManager

getLibraryContentManager

public LibraryContentManager getLibraryContentManager()

Obtains an instance of ibi.broker.api.cci.LibraryContentManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.LibraryContentManager

getConfigManager

public ConfigManager getConfigManager()

Obtains an instance of ibi.broker.api.cci.ConfigManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.ConfigManager

getUserManager

public UserManager getUserManager()

Obtains an instance of ibi.broker.api.cci.UserManager that is to be used in conjunction with this connection instance.

Returns:

ibi.broker.api.cci.UserManager

getSecurityToken

public java.lang.String getSecurityToken()

getMrManager

public ibi.broker.system.mre.CASTER_MREManager getMrManager(java.lang.String owner)
                                                     throws java.lang.Exception

Throws:

java.lang.Exception

getUser

public User getUser()

Obtain the username of the current ReportCaster user who is accessing this CasterConnection instance.

Returns:

ibi.broker.api.data.user.User

setMrRole

public void setMrRole(java.lang.String mrRole)

getAnnotationManager

public ibi.broker.api.cci.AnnotationManager getAnnotationManager()

setLogWriter

public void setLogWriter(java.io.PrintWriter logWriter)

getLogWriter

public java.io.PrintWriter getLogWriter()

getApplicationPreference

public ibi.broker.api.data.preference.application.ApplicationPreference getApplicationPreference()

setApplicationPreference

public void setApplicationPreference(ibi.broker.api.data.preference.application.ApplicationPreference applicationPreference)