ibi.broker.api
Class CasterManagedConnectionFactory

java.lang.Object
  ibi.broker.api.CasterManagedConnectionFactory

All Implemented Interfaces:

java.io.Serializable, javax.resource.spi.ManagedConnectionFactory

Direct Known Subclasses:

CasterManagedConnectionFactoryMigration

public class CasterManagedConnectionFactory
extends java.lang.Object
implements javax.resource.spi.ManagedConnectionFactory

 Within the ReportCaster API, the CasterManagedConnectionFactory 
 class along with the CasterConnectionFactoryand 
 CasterConnection classes are the primary means for
 obtaining connections to ReportCaster. The three classes facilitate the application 
 client component's ability to obtain a connection to 
 ReportCaster repository and Distribution Server and are implementations of
 the JCA's ManagedConnectionFactory ,
 ConnectionFactory, and Connection classes
 respectively. These three classes together form the basis of ReportCaster's
 implementation of the J2EE CCI interfaces. 
 

 The CasterManagedConnectionFactory class acts essentially as a
 factory for both CasterConnectionFactory instances and 
 ManagedConnection instances. Whereas the
 CasterConnectionFactory object creates connections to the 
 ReportCaster Repository (in the form of CasterConnection instances), 
 CasterManagedConnectionFactory creates managed connections (i.e., 
 ManagedConnection instances), which represent the actual physical 
 connection to ReportCaster. This is the class which is responsible for all the
 Application Server level connection pooling facilities available through JCA. When an 
 application server needs to create a connection factory it calls the 
 createConnectionFactory method of CasterManagedConnnectionFactory, passing in an 
 instance of ConnectionManager. This
 ConnectionManager instance is what is called by the client application 
 component (EJB, Servlets, JSP, as well as the ReportCaster application itself) when it 
 issues a call to  CasterConnectionFactory.getConnection() in order to obtain a connection 
 handle (i.e., CasterConnection to ReportCaster.
 The main methods CasterConnectioFactory uses to support its functionality are the
 following:
 

 
 createConnectionFactory - returns and instance of the connection 
 factory that can be used by application clients (including ReportCaster).
 
createManagedConnection - creates a new ManagedConnection
 
matchManagedConnections - returns from a pool of ManageedConnection 
 instances a ManagedConnection the matches the client's security information.

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

Field Summary

static int	CONSOLE_MODE
static int	DB Repository type representing a RDMS database.
static int	FULLFUNCTION_MODE
static int	LDAP Repository type representing a LDAP directory.

Constructor Summary

CasterManagedConnectionFactory()
Constructor for CasterManagedConnectionFactory.

Method Summary

java.lang.Object	createConnectionFactory() Creates a CasterConnectionFactory instance.
java.lang.Object	createConnectionFactory(javax.resource.spi.ConnectionManager cxManager) Creates a CasterConnectionFactory instance.
javax.resource.spi.ManagedConnection	createManagedConnection(javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo connInfo) Creates a new physical connection to ReportCaster's underlying Repository.
java.io.PrintWriter	getLogWriter() Obtains the log writer for this CasterManagedConnectionFactory instance.
int	getServerStatus()
javax.resource.spi.ManagedConnection	matchManagedConnections(java.util.Set set, javax.security.auth.Subject subject, javax.resource.spi.ConnectionRequestInfo connReqInfo) Determines whether there is an existing connection in the connection pool (which contains a pool of ManagedConnection instances and stored in the connection set parameter, set) that can be used as a connection to the ReportCaster Repository.
void	setIbiDocumentRoot(java.lang.String ibiDocumentRoot)
void	setLogWriter(java.io.PrintWriter arg0) Sets the log writer for this CasterManagedConnectionFactory instance.
void	setPortNumber(java.lang.String agentPort) Specifies the ReportCaster Distribution Server's port number.
void	setReporsitoryType(int type) Specifies the repository type.
void	setServerName(java.lang.String agentNode) Specifies the server name where ReportCaster Distribution Server is located.
void	setTrustedKeyFile(java.lang.String file) Deprecated. this method is no longer needed.

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.resource.spi.ManagedConnectionFactory

equals, hashCode

Field Detail

DB

public static final int DB

Repository type representing a RDMS database.

See Also:

Constant Field Values

LDAP

public static final int LDAP

Repository type representing a LDAP directory.

See Also:

Constant Field Values

FULLFUNCTION_MODE

public static final int FULLFUNCTION_MODE

See Also:

Constant Field Values

CONSOLE_MODE

public static final int CONSOLE_MODE

See Also:

Constant Field Values

Constructor Detail

CasterManagedConnectionFactory

public CasterManagedConnectionFactory()

Constructor for CasterManagedConnectionFactory.

Method Detail

createConnectionFactory

public java.lang.Object createConnectionFactory(javax.resource.spi.ConnectionManager cxManager)
                                         throws javax.resource.ResourceException

Creates a CasterConnectionFactory instance. In this case, the connection factory instance gets initialized with the passed ConnectionManager. Associated with the connection factory are a CasterManagedConnectionFactory or optionally a ConnectionManager, which in the managed scenario is provided by the J2EE Application Server.

Specified by:

createConnectionFactory in interface javax.resource.spi.ManagedConnectionFactory

Parameters:

cxManager - - Connection Manager to be associated with created CasterConnectionFactory instance

Throws:

javax.resource.ResourceException

See Also:

ManagedConnectionFactory.createConnectionFactory(javax.resource.spi.ConnectionManager)

createConnectionFactory

public java.lang.Object createConnectionFactory()
                                         throws javax.resource.ResourceException

Creates a CasterConnectionFactory instance. In this case, the CasterConnectionFactory instance gets initialized with a default ConnectionManager provided by the resource adapter.

Specified by:

createConnectionFactory in interface javax.resource.spi.ManagedConnectionFactory

Returns:

Application specific Connection Factory instance (i.e., CasterConnectionFactory) or javax.resource.cci.ConnectionFactory instance

Throws:

javax.resource.ResourceException - - Generic exception

See Also:

ManagedConnectionFactory.createConnectionFactory()

createManagedConnection

public javax.resource.spi.ManagedConnection createManagedConnection(javax.security.auth.Subject subject,
                                                                    javax.resource.spi.ConnectionRequestInfo connInfo)
                                                             throws javax.resource.ResourceException

Creates a new physical connection to ReportCaster's underlying Repository. CasterManagedConnectionFactory uses the security information (passed as a Subject) and additional ConnectionRequestInfo from the client application component which is generating the request to create a new connection.

Specified by:

createManagedConnection in interface javax.resource.spi.ManagedConnectionFactory

Parameters:

subject - - JAAS concept representing a grouping of related security information for a single user/entity (i.e, the caller). It includes identities (each known as a Principal), and security-related attributes called Credentials. In the case of container managed sign-on (which we do not currently support) the Subject object comes from the security contract that is a part of the system contract between the application server and the resource adapter. In the case of application managed sign-on (which we do support), security information is sent as a ConnnectionRequestInfo object, and the subject that is sent to the resource adapter is null.

connInfo - Security related connection request information (e.g., username and password).

Throws:

javax.resource.ResourceException

See Also:

ManagedConnectionFactory.createManagedConnection(javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo)

matchManagedConnections

public javax.resource.spi.ManagedConnection matchManagedConnections(java.util.Set set,
                                                                    javax.security.auth.Subject subject,
                                                                    javax.resource.spi.ConnectionRequestInfo connReqInfo)
                                                             throws javax.resource.ResourceException

Determines whether there is an existing connection in the connection pool (which contains a pool of ManagedConnection instances and stored in the connection set parameter, set) that can be used as a connection to the ReportCaster Repository. The criteria for making a match is based on the security information of the current user as represented in the Subject instance (non-null in managed mode) and ConnectionRequestInfo instance. This method returns a single ManagedConnection instance that is the best match for handling the connection allocation request. If no match is found, the method will return null.

Specified by:

matchManagedConnections in interface javax.resource.spi.ManagedConnectionFactory

Throws:

javax.resource.ResourceException

See Also:

ManagedConnectionFactory.matchManagedConnections(java.util.Set, javax.security.auth.Subject, javax.resource.spi.ConnectionRequestInfo)

setLogWriter

public void setLogWriter(java.io.PrintWriter arg0)
                  throws javax.resource.ResourceException

Sets the log writer for this CasterManagedConnectionFactory instance. The log writer is a character output stream to which all logging and tracing messages will be printed. The J2EE Application Server manages the association of output stream with this CasterManagedConnectionFactory. When an instance of CasterManagedConnectionFactory is created the log writer is initially null, in other words, logging is disabled. Once a log writer is associated with a CasterManagedConnectionFactory instance, logging and tracing is enabled.

The ManagedConnection instances created by CasterManagedConnectionFactory inherits the log writer, which can be overridden by the Application Server using this method to specify the logging and tracing for a managed connection. Once a managed connection object is returned to the connection pool, this instance of CasterManagedConnectionFactory should be set to null.

Specified by:

setLogWriter in interface javax.resource.spi.ManagedConnectionFactory

Throws:

javax.resource.ResourceException

See Also:

ManagedConnectionFactory.setLogWriter(java.io.PrintWriter)

getLogWriter

public java.io.PrintWriter getLogWriter()
                                 throws javax.resource.ResourceException

Obtains the log writer for this CasterManagedConnectionFactory instance. The log writer is a character output stream to which all logging and tracing messages pertaining to this Code>CasterManagedConnectionFactory instance will be printed. The J2EE Application Server manages the association of output stream with this CasterManagedConnectionFactory. When an instance of CasterManagedConnectionFactory is created the log writer is initially null, in other words, logging is disabled. Once a log writer is associated with a CasterManagedConnectionFactory object, logging and tracing is enabled.

Specified by:

getLogWriter in interface javax.resource.spi.ManagedConnectionFactory

Throws:

javax.resource.ResourceException

See Also:

ManagedConnectionFactory.getLogWriter()

setServerName

public void setServerName(java.lang.String agentNode)

Specifies the server name where ReportCaster Distribution Server is located. The server name must be set before the Application Server can create an managed connection instance (resulting ultimately in a CasterConnection object)from the connection pool. This will accept either the TCP/IP address of the server or the host name.

Parameters:

agentNode - represents a server agent.

setPortNumber

public void setPortNumber(java.lang.String agentPort)

Specifies the ReportCaster Distribution Server's port number. The default value is 8200.

Parameters:

agentPort - The port number as a String.

setReporsitoryType

public void setReporsitoryType(int type)

Specifies the repository type. The two available types of ReportCaster repositories are: DB(database) and LDAP (LDAP directory).

Parameters:

type - Repository type.

setTrustedKeyFile

public void setTrustedKeyFile(java.lang.String file)

Deprecated. this method is no longer needed.

Sets the ReportCaster Trusted Key File. A Trusted Key File is required if ReportCaster authentication is performed by trusted Managed Reporting sign-on. This is necessary when your application is not run from the ReportCaster Web application.

Parameters:

file - The name of the Trusted Key File.

getServerStatus

public int getServerStatus()
                    throws CasterException

Throws:

CasterException

setIbiDocumentRoot

public void setIbiDocumentRoot(java.lang.String ibiDocumentRoot)