ibi.broker.api.cci
Class CasterConnectionFactory

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

All Implemented Interfaces:

java.io.Serializable, javax.naming.Referenceable, javax.resource.cci.ConnectionFactory

public class CasterConnectionFactory
extends java.lang.Object
implements javax.resource.cci.ConnectionFactory

 This class is used with the CasterConnection and 
 CasterManagedConnectionFactory classes to connect to ReportCaster. 
 These three classes are implementations of the JCA's ConnectionFactory,
 Connection, and ManagedConnectionFactory classes, respectively, and 
 enable the application client components to obtain connections. Together, these three
 classes form the basis of ReportCaster's implementation of the J2EE CCI interfaces.

 The J2EE application components, which can include EJBs, JavaBeans, JSPs, and 
 servlets, access a particular ReportCaster instance using the 
 CasterConnectionFactory, which provides a repository of connection 
 objects for the requesting client. Whether the client (which may be ReportCaster 
 itself) accesses the underlying data repository directly (non-managed mode) or 
 indirectly through a J2EE application server (managed mode), 
 CasterConnectionFactory allocates connection handles in the form 
 of CasterConnnection instances. 

 A CasterConnection instance serves as a main endpoint in the dialog 
 between the requesting clients, application server, and the underlying resource. 
 This dialog is mediated by the resource adapter, which is implemented within the 
 ReportCaster API as a design pattern, not as a packaged JAR requiring an application 
 server level deployment descriptor. The class that provides the point of access is 
 CasterConnectionFactory. 

 The code below illustrates how the CasterConnectionFactory class is 
 used. This sample code below 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

See Also:

Serialized Form

Constructor Summary

CasterConnectionFactory(javax.resource.spi.ConnectionManager cm, javax.resource.spi.ManagedConnectionFactory mcf)
Primary constructor for CasterConnectionFactory.

Method Summary

javax.resource.cci.Connection	getConnection() Obtains a CasterConnection instance of the connection handle to satisfy a connection request for the current user.
javax.resource.cci.Connection	getConnection(javax.resource.cci.ConnectionSpec credential) Obtains a CasterConnection instance of the connection handle to satisfy a connection request from the user identified in the ConnectionSpec.
javax.resource.cci.Connection	getConnection(javax.resource.cci.ConnectionSpec credential, boolean specialCheckingMRRole, boolean useConsoleMode)
javax.resource.cci.ResourceAdapterMetaData	getMetaData() Obtains metadata for the Resource Adapter.
javax.resource.cci.RecordFactory	getRecordFactory() Obtains a RecordFactory object, used to create generic Record instances.
javax.naming.Reference	getReference() Obtains the Reference instance.
java.util.Hashtable	getSendMode()
boolean	isWebAuthenticationEnabled()
void	setAuthenticationExit(java.lang.String exit) Specifies the AuthenticationExit's class or interface name.
void	setConfig(ibi.broker.system.config.CasterConfig config) Assigns the Configuration file for the Distribution server.
void	setDSTTraceWorker(ibi.broker.util.DSTTraceWorker traceWorker)
void	setReference(javax.naming.Reference arg0) Sets the Reference instance.
void	setRepositoryType(int i) Sets the ReportCaster repository type specified as an integer value.
void	setSendMode(java.util.Hashtable sendMode)
void	setWebAuthenticationEnabled(boolean flag) Specifies the value of a boolean flag which indicates whether or not WebAuthentication is turned on.

Methods inherited from class java.lang.Object

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

Constructor Detail

CasterConnectionFactory

public CasterConnectionFactory(javax.resource.spi.ConnectionManager cm,
                               javax.resource.spi.ManagedConnectionFactory mcf)

Primary constructor for CasterConnectionFactory. This always passes in instances of ConnectionManager and ManagedConnectionFactory, which will eventually be responsible for facilitating the physical connection to the ReportCaster repository and passing the CasterConnection connection handle to the client making a call via this CasterConnectionFactory instance.

Method Detail

setDSTTraceWorker

public void setDSTTraceWorker(ibi.broker.util.DSTTraceWorker traceWorker)

setSendMode

public void setSendMode(java.util.Hashtable sendMode)

getSendMode

public java.util.Hashtable getSendMode()

setConfig

public void setConfig(ibi.broker.system.config.CasterConfig config)

Assigns the Configuration file for the Distribution server. This takes the name of the file which specifies the configuration properties of the Distribution Server. This method is not meant to be called by the API user.

Parameters:

config - name of distribution server configuration file.

getConnection

public javax.resource.cci.Connection getConnection()
                                            throws javax.resource.ResourceException

Obtains a CasterConnection instance of the connection handle to satisfy a connection request for the current user. This getConnection variant should be used when an application component requires that the container manage sign-on/security. This scenario is termed container- managed sign-on whereby the client component calling the method does not pass in any security information but instead leaves that up to the application server.

Specified by:

getConnection in interface javax.resource.cci.ConnectionFactory

Returns:

A CasterConnection instance.

Throws:

javax.resource.ResourceException - - Failed to get a CasterConnection instance. Examples of error cases are:

• Invalid configuration of CasterManagedConnectionFactory-- example: invalid server name
  
• Application server-internal error--example: connection pool related error
  
• Communication error
  
• EIS-specific error--example: EIS not active
  
• Resource adapter-internal error
  
• Security related error; example: invalid user
  
• Failure to allocate system resources
  

See Also:

getConnection(javax.resource.cci.ConnectionSpec)

getConnection

public javax.resource.cci.Connection getConnection(javax.resource.cci.ConnectionSpec credential)
                                            throws javax.resource.ResourceException

Obtains a CasterConnection instance of the connection handle to satisfy a connection request from the user identified in the ConnectionSpec. This version of getConnection should be used in the case where the application component manages the security (i.e., component-managed sign on). In contrast to the previous case where sign-on is managed by the application server container, here the client passes in security credentials such as username and password directly through the ConnectionSpec instance.

Specified by:

getConnection in interface javax.resource.cci.ConnectionFactory

Parameters:

credential - A reference to the ConnectionSpec object used to specify the users security credentials.

Returns:

CasterConnection instance.

Throws:

javax.resource.ResourceException - - Failed to get a CasterConnection instance. Examples of error cases are:

• Invalid configuration of CasterManagedConnectionFactory-- example: invalid server name
  
• Application server-internal error--example: connection pool related error
  
• Communication error
  
• EIS-specific error--example: EIS not active
  
• Resource adapter-internal error
  
• Security related error; example: invalid user
  
• Failure to allocate system resources
  

See Also:

getConnection()

getConnection

public javax.resource.cci.Connection getConnection(javax.resource.cci.ConnectionSpec credential,
                                                   boolean specialCheckingMRRole,
                                                   boolean useConsoleMode)
                                            throws javax.resource.ResourceException

Throws:

javax.resource.ResourceException

getRecordFactory

public javax.resource.cci.RecordFactory getRecordFactory()
                                                  throws javax.resource.ResourceException

Obtains a RecordFactory object, used to create generic Record instances. This feature is currently unavailable to API users.

Specified by:

getRecordFactory in interface javax.resource.cci.ConnectionFactory

Returns:

Always return null.

Throws:

javax.resource.ResourceException

See Also:

ConnectionFactory.getRecordFactory()

getMetaData

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

Obtains metadata for the Resource Adapter. An invocation of this method does not require an active connection to the repository.

Specified by:

getMetaData in interface javax.resource.cci.ConnectionFactory

Returns:

An instance of ResourceAdapterMetaData.

Throws:

javax.resource.ResourceException - - Failed to get metadata information about the resource adapter.

See Also:

getMetaData()

setReference

public void setReference(javax.naming.Reference arg0)

Sets the Reference instance. A Reference represents a way of recording address information about objects which themselves are not directly bound to a naming system (such as JNDI). Such objects can implement the Referenceable interface as a way for programs that use that object to determine what its Reference is. For example, when binding an object, if an object implements the Referenceable (defined in the javax.naming.Referenceable interface), the getReference() method which is called by the deployment code can be invoked on the object to get its Reference to use for binding.

Parameters:

arg0 - - A Reference instance

See Also:

Referenceable.setReference(javax.naming.Reference), getReference()

getReference

public javax.naming.Reference getReference()
                                    throws javax.naming.NamingException

Obtains the Reference instance. A Reference represents a way of recording address information about objects that are not directly bound to a naming system (such as JNDI). These objects can implement the Referenceable interface so that the programs calling them can identify what their references are. When binding an object, for example, if the object implements the Referenceable (defined in the javax.naming.Referenceable interface), the getReference() method is called by the deployment code and can be applied to the object to get its Reference.

Specified by:

getReference in interface javax.naming.Referenceable

Returns:

The non-null Reference of this object.

Throws:

javax.naming.NamingException - - if a naming exception was encountered while retrieving the reference.

See Also:

Referenceable.getReference()

setWebAuthenticationEnabled

public void setWebAuthenticationEnabled(boolean flag)

Specifies the value of a boolean flag which indicates whether or not WebAuthentication is turned on. Web Authentication refers to the client component's ability to authenticate ReportCaster users via the Web (for example by using Servlet based http Request/Response header strings)

Parameters:

flag - The Boolean value.

isWebAuthenticationEnabled

public boolean isWebAuthenticationEnabled()

setAuthenticationExit

public void setAuthenticationExit(java.lang.String exit)

Specifies the AuthenticationExit's class or interface name. Used in conjunction with client side WebAuthentication.

Parameters:

exit - name of class or interface which specifies the WebAuthentication exit point.

setRepositoryType

public void setRepositoryType(int i)

Sets the ReportCaster repository type specified as an integer value. The two available options are LDAP and DB indicating a LDAP-based repository or a RDBMS-based repository respectively. Refer to the field summary of the CasterManagedConnectionFactory class.

Parameters:

i - DB ibi.broker.api.CasterManagedConnectionFactory.DB;
LDAP- ibi.broker.api.CasterManagedConnectionFactory.LDAP;