oracle.odi.core

Class OdiInstance

java.lang.Object

oracle.odi.core.OdiInstance

public class OdiInstance
extends java.lang.Object

Represents an instance of ODI master / work repositories. Can be defined as a unique ODI master repository, or as a couple ODI master / work repositories.

OdiInstance is the central class in ODI Core Infrastructure, providing low level infrastructure services required by ODI consumers needing read / write access to an ODI master / work repositories couple:

• Security management allowing ODI users authentication and authorization check
• Transaction and persistence management allowing transactional access (read and write) to underlying repositories

Therefore, an instance of ODI serves as an entry points for ODI master / work repositories consumers (ODI components / applications, as well as external consumers that needs to perform ODI repositories data access). It is created from the static factory method createInstance(OdiInstanceConfig) which basically checks repository consistency and create required resources such as JDBC DataSources and JPA persistence service (optional) against underlying repositories. An OdiInstance is expected to be closed by a call to the method close() in order to release any held resources.

An OdiInstance object is expected to be shared across multiple ODI users and threads that want to access same couple of ODI master / work repositories. However any number of OdiInstance objects can be created by an application and there can be several OdiInstances referencing the same master / work DB repositories. OdiInstances are agnostic about existence of each others. The source of truth as far as the repositories data is concerned is the repository DB. Creation of an OdiInstance object is an operation that maybe time and resource consuming. Typically, during ODI instance creation, JDBC DataSources and JPA persistence provider are initialized. Also, note that during repository consistency check, some queries are issued against repositories.

Additionally and for convenience regarding actual legacy layer code base, an instance of ODI also provides external (i.e. not ODI repositories) JDBC DataSources management and lookup capabilities. Such DataSource management and lookup is typically required during ETL processes to access target and source data stores. Application / domain services implementation can rely on this to access external data servers.

Note: access to an OdiInstance object should be restricted to "trusted" users only. Applications should take care to never provide a reference to an OdiInstance to ELT developers (e.g. from OdiRef).

Note: OdiInstance class implements the depreciated IOdiInstance interface for code compatibility purpose. This would ease migration of code using some depreciated APIs such as OdiPlatform.

Since:

11.1.1.3.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OdiInstance.IOdiInstanceListener

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	MASTER_VALIDATION_QUERY

Method Summary

Modifier and Type	Method and Description
static void	addOdiInstanceListener(OdiInstance.IOdiInstanceListener listener) Add a listener that will be notified after an OdiInstance is created, and when it is closed.
void	close() Close this OdiInstance, releasing any held resources.
IOdiEntityManager	createEntityManager() Create an application-managed IOdiEntityManager.
static OdiInstance	createInstance(OdiInstanceConfig pConfig) Create an OdiInstance object.
IOdiEntity	findById(java.lang.Class pRequiredType, java.io.Serializable pId)
WorkRepository[]	getAllWorkRepositories(MasterRepository pMasterRepository) Gets a list of WorkRepository that associated with the given MasterRepository
WorkRepository[]	getAllWorkRepositories(MasterRepository pMasterRepository, boolean ignoreEx)
oracle.odi.core.audit.OdiAuditContext	getAuditContext()
oracle.security.jps.service.audit.Auditor	getAuditor()
OdiInstanceConfig	getConfig() Obtains this OdiInstance configuration object.
IFinder	getFinder(java.lang.Class pEntityType) Convenience method to get a finder when there is no requirement to find an entity using an existing entity manager.
int	getInstanceId()
java.lang.String	getLoginApplicationName()
MasterRepository	getMasterRepository() Return MasterRepository associated with this OdiInstance.
boolean	getNeedAudit()
IOdiEntityManagerFactory	getOdiEntityManagerFactory() Gets IOdiEntityManagerFactory bounds to this OdiInstance.
SecurityManager	getSecurityManager() Gets SecurityManager bounds to this OdiInstance.
IOdiEntityManager	getTransactionalEntityManager() Gets managed IOdiEntityManager, attached to the current transaction.
java.sql.Connection	getTransactionalMasterConnection() Gets managed JDBC Connection against master repository.
java.sql.Connection	getTransactionalWorkConnection() Gets managed JDBC Connection against work repository.
ITransactionManager	getTransactionManager() Gets the instance of ITransactionManager bounds to this OdiInstance
WorkRepository	getWorkRepository() Return WorkRepository associated with this OdiInstance.
boolean	isClosed() Returns whether this OdiInstance has been closed, or not.
boolean	isPersistable(java.lang.Class theClass) Return true if the specified class type is persistable via the eclipselink persistence.
javax.sql.DataSource	lookupDataSource(oracle.odi.core.datasource.DataSourceDefinition pDefinition) Looks up JDBC DataSource for given DataSourceDefinition.
void	releaseDataSource(oracle.odi.core.datasource.DataSourceDefinition pDefinition) Release the JDBC DataSource with given definition if managed inside this OdiInstance.
static void	removeOdiInstanceListener(OdiInstance.IOdiInstanceListener listener) Remove an ODI instance listener that was previously added.
void	saveEntity(IOdiEntity entity) Convenience method to save an IOdiEntity.
void	saveEntityManager(IOdiEntityManager em) Handy helper method to save the changes made in an entity manager to a transaction.

Methods inherited from class java.lang.Object

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

Field Detail

MASTER_VALIDATION_QUERY

public static final java.lang.String MASTER_VALIDATION_QUERY

See Also:

Constant Field Values

Method Detail

getInstanceId

public int getInstanceId()

createInstance

public static OdiInstance createInstance(OdiInstanceConfig pConfig)
                                  throws OdiConfigurationException

Create an OdiInstance object.

Parameters:

pConfig - ODI configuration

Returns:

a new instance of ODI with specified configuration

Throws:

java.lang.IllegalArgumentException - in case given config object is null

OdiConfigurationException - in case of any configuration issue (see OdiConfigurationException exceptions hierarchy)

getLoginApplicationName

public java.lang.String getLoginApplicationName()

addOdiInstanceListener

public static void addOdiInstanceListener(OdiInstance.IOdiInstanceListener listener)

Add a listener that will be notified after an OdiInstance is created, and when it is closed.

removeOdiInstanceListener

public static void removeOdiInstanceListener(OdiInstance.IOdiInstanceListener listener)

Remove an ODI instance listener that was previously added.

Parameters:

listener -

isPersistable

public boolean isPersistable(java.lang.Class theClass)

Return true if the specified class type is persistable via the eclipselink persistence.

Parameters:

theClass - The class type to be checked.

Returns:

getConfig

public OdiInstanceConfig getConfig()

Obtains this OdiInstance configuration object.

Returns:

an OdiInstanceConfig object

getMasterRepository

public MasterRepository getMasterRepository()

Return MasterRepository associated with this OdiInstance.

Returns:

a MasterRepository object

Throws:

OdiRuntimeException - if this OdiInstance has been closed

getWorkRepository

public WorkRepository getWorkRepository()

Return WorkRepository associated with this OdiInstance. This method will return null if the OdiInstance is connected only to a master repository i.e. the OdiInstanceConfig used to create the OdiInstance had no WorkRepositoryDbInfo specified.

Returns:

a WorkRepository object

Throws:

OdiRuntimeException - if this OdiInstance has been closed

lookupDataSource

public javax.sql.DataSource lookupDataSource(oracle.odi.core.datasource.DataSourceDefinition pDefinition)

Looks up JDBC DataSource for given DataSourceDefinition. Subsequent calls to this method with a same / equals definition will return the same DataSource instance each time.

Once a DataSource has been looked up, release it by calling releaseDataSource(DataSourceDefinition).

Parameters:

pDefinition - DataSource definition

Returns:

JDBC DataSource

Throws:

java.lang.IllegalArgumentException - if given definition is null

OdiRuntimeException - if this OdiInstance has been closed

See Also:

releaseDataSource(DataSourceDefinition)

releaseDataSource

public void releaseDataSource(oracle.odi.core.datasource.DataSourceDefinition pDefinition)

Release the JDBC DataSource with given definition if managed inside this OdiInstance. This will release any resource held by related DataSource.

Parameters:

pDefinition - definition of the DataSource to be released

Throws:

java.lang.IllegalArgumentException - if given definition is null

OdiRuntimeException - if this OdiInstance has been closed

See Also:

lookupDataSource(DataSourceDefinition)

getTransactionalMasterConnection

public java.sql.Connection getTransactionalMasterConnection()

Gets managed JDBC Connection against master repository.

Obtained connection is attached to the current transaction if exists, or a new one if no transaction is in progress.

Returns:

Master repository current Connection

Throws:

IllegalOdiInstanceStateException - if this OdiInstance has been closed

getTransactionalWorkConnection

public java.sql.Connection getTransactionalWorkConnection()

Gets managed JDBC Connection against work repository.

Obtained connection is attached to the current transaction if exists, or a new one if no transaction is in progress. Life-cycle of the connection is managed within the transaction.

Returns:

Work repository managed Connection

Throws:

IllegalOdiInstanceStateException - if this OdiInstance has been closed

getTransactionalEntityManager

public IOdiEntityManager getTransactionalEntityManager()

Gets managed IOdiEntityManager, attached to the current transaction.

Life-cycle of the IOdiEntityManager is managed within the transaction. If there is no current transaction, this method returns a read-only IOdiEntityManager (only the find methods will be allowed).

Returns:

Managed IOdiEntityManager

Throws:

OdiRuntimeException - if this OdiInstance has been closed

OdiRuntimeException - if this OdiInstance only support limited persistence service

close

public void close()

Close this OdiInstance, releasing any held resources.

Any looked up DataSources are released, as well as persistence resources. After an OdiInstance is closed, all methods invoked on it will throw an OdiRuntimeException, except for isCloded(), which will return true.

Throws:

OdiRuntimeException - if the OdiInstance has been already closed

isClosed

public boolean isClosed()

Returns whether this OdiInstance has been closed, or not.

Returns:

true if it has been closed, false otherwise.

createEntityManager

public IOdiEntityManager createEntityManager()

Create an application-managed IOdiEntityManager.

Such an application-managed IOdiEntityManager need to be manually closed when required by the application.

This type of IOdiEntityManager is mainly for extended persistent context management. An extended persistent context isn't bound to a single transaction.

Returns:

an application managed IOdiEntityManager

Throws:

OdiRuntimeException - if this OdiInstance has been closed

OdiRuntimeException - if this OdiInstance only support limited persistence service

getOdiEntityManagerFactory

public IOdiEntityManagerFactory getOdiEntityManagerFactory()

Gets IOdiEntityManagerFactory bounds to this OdiInstance.

Returns:

a IOdiEntityManagerFactory that can be used to create an application managed IOdiEntityManager

Throws:

OdiRuntimeException - if this OdiInstance has been closed

OdiRuntimeException - if this OdiInstance only support limited persistence service

getSecurityManager

public SecurityManager getSecurityManager()

Gets SecurityManager bounds to this OdiInstance.

Throws:

OdiRuntimeException - if this OdiInstance has been closed

getTransactionManager

public ITransactionManager getTransactionManager()

Gets the instance of ITransactionManager bounds to this OdiInstance

Returns:

ITransactionManager

getAllWorkRepositories

public WorkRepository[] getAllWorkRepositories(MasterRepository pMasterRepository)

Gets a list of WorkRepository that associated with the given MasterRepository

Parameters:

pMasterRepository - the MasterRepository

Returns:

a list of WorkRepository

getAllWorkRepositories

public WorkRepository[] getAllWorkRepositories(MasterRepository pMasterRepository,
                                               boolean ignoreEx)

saveEntityManager

public void saveEntityManager(IOdiEntityManager em)

Handy helper method to save the changes made in an entity manager to a transaction.

getAuditContext

public oracle.odi.core.audit.OdiAuditContext getAuditContext()

getNeedAudit

public boolean getNeedAudit()

getAuditor

public oracle.security.jps.service.audit.Auditor getAuditor()

getFinder

public IFinder getFinder(java.lang.Class pEntityType)

Convenience method to get a finder when there is no requirement to find an entity using an existing entity manager. See IOdiEntityManager.getFinder(Class)

Parameters:

pEntityType - the entity type the finder has to provide support for

Returns:

the finder supporting the given entity type

saveEntity

public void saveEntity(IOdiEntity entity)

Convenience method to save an IOdiEntity. Transactioning is handled under the covers. Entity may be new or existing.

findById

public IOdiEntity findById(java.lang.Class pRequiredType,
                           java.io.Serializable pId)