sailpoint.api

## Interface PersistenceManager

All Superinterfaces:
  Resolver

All Known Subinterfaces:
  SailPointContext

    public interface PersistenceManager
    extends Resolver

Interface implemented by classes that provide persistence services.

### Nested Class Summary

Nested Classes
`static class` `PersistenceManager.LockParameters` Encapsulation of lock parameters.
`static class` `PersistenceManager.LockPhase`

### Field Summary

Fields
`static java.lang.String` `LOCK_NAME` Option for lockObject that specifies the name of the user that will hold the lock.
`static java.lang.String` `LOCK_TYPE` Option for lockObject that specifies the type of lock to be acquired.
`static java.lang.String` `LOCK_TYPE_PERSISTENT` A value for the LOCK_TYPE option that selects a persistent lock.
`static java.lang.String` `LOCK_TYPE_TRANSACTION` A value for the LOCK_TYPE option that selects a transaction lock.

### Method Summary

All Methods Instance Methods Abstract Methods Default Methods
`void` `attach(SailPointObject object)` Attach the given SailPointObject possibly loaded by a different SailPointContext to this SailPointContext.
`void` `clearHighLevelCache()` Clears a "high level" cache.
`java.lang.Object` `clone()` Optional clone method.
`void` `close()` Close this PersistenceManager and release any resources in use.
`void` `commitTransaction()` Commit the current transaction that was started with `startTransaction()`.
`void` `commitTransaction(boolean startNewTransaction)` Commit the current transaction that was started with `startTransaction()`.
`int` `countObjects(java.lang.Class cls, QueryOptions options)` Counts the number of objects that match a criteria.
`void` `decache()` Remove all objects the cache.
`void` `decache(SailPointObject obj)` Remove the object from the cache.
`void` `enableStatistics(boolean b)` Enable or disable collection of statistics.
`<T extends SailPointObject> T` `getObjectById(java.lang.Class<T> cls, java.lang.String id)` Retrieve an object by id.
`<T extends SailPointObject> T` `getObjectByName(java.lang.Class<T> cls, java.lang.String name)` Retrieve an object by name.
`<T extends SailPointObject> java.util.List<T>` `getObjects(java.lang.Class<T> cls)` Return all objects of a given class.
`<T extends SailPointObject> java.util.List<T>` `getObjects(java.lang.Class<T> cls, QueryOptions ops)` Return all objects of a given class, constrained by Filters in the QueryOptions.
`PersistenceOptions` `getPersistenceOptions()` Get current options that control how objects are managed in the Hibernate session.
`default <T> java.util.Iterator<T>` `getPropertyIterator(java.lang.Class<? extends SailPointObject> cls, QueryOptions options, java.lang.String property)` Perform a projection search for a single object property and return an iterator.
`default <T> java.util.List<T>` `getPropertyList(java.lang.Class<? extends SailPointObject> cls, QueryOptions options, java.lang.String property)` Perform a projection search for a single object property and return a list.
`<T extends SailPointObject> T` `getUniqueObject(java.lang.Class<T> cls, Filter f)` Retrieve an object matching a Filter.
`<T extends SailPointObject> T` `getUniqueObject(T example)` Retrieve an object whose properties match those specified in an example object.
`void` `importObject(SailPointObject obj)` Import an object into the persistent store.
`<T extends SailPointObject> T` `lockObject(java.lang.Class<T> clazz, PersistenceManager.LockParameters params)` This method should be the entry point for all public locking calls.
`<T extends SailPointObject> T` `lockObjectById(java.lang.Class<T> cls, java.lang.String id, java.util.Map<java.lang.String,java.lang.Object> options)` Retrieve an object with a long-duration lock.
`<T extends SailPointObject> T` `lockObjectByName(java.lang.Class<T> cls, java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> options)` Retrieve an object with a long-duration lock.
`void` `printStatistics()` Print the collected statistics.
`void` `reconnect()` Reconnect the PersistenceManager to the persistent store (for example, by reconnecting to the database).
`void` `releasePersistentLocks()` Ensure any persistent locks acquired are released before releasing this context.
`void` `removeObject(SailPointObject obj)` Remove an object from the persistent store.
`<T extends SailPointObject> void` `removeObjects(java.lang.Class<T> cls, QueryOptions ops)` Bulk remove object based on the Filter defined in the QueryOptions.
`boolean` `requiresJoin(java.lang.Class<? extends SailPointObject> cls, QueryOptions options, java.util.List<java.lang.String> properties)` Returns whether the resulting query for the specified QueryOptions and properties requires sql joins, making duplicate results possible.
`void` `rollbackTransaction()` Rollback the current transaction that was started with `startTransaction()`.
`void` `saveObject(SailPointObject obj)` Save an object in the persistent store.
`<T extends SailPointObject> java.util.Iterator<T>` `search(java.lang.Class<T> cls, QueryOptions options)` Return a set of objects matching the query options.
`<T extends SailPointObject> java.util.Iterator<java.lang.Object[]>` `search(java.lang.Class<T> cls, QueryOptions options, java.util.List<java.lang.String> properties)` Perform a projection search for selected object properties and return an iterator.
`<T extends SailPointObject> java.util.Iterator<java.lang.Object[]>` `search(java.lang.Class<T> cls, QueryOptions options, java.lang.String properties)` Perform a projection search for selected object properties and return an iterator.
`java.util.Iterator` `search(java.lang.String query, java.util.Map<java.lang.String,java.lang.Object> args, QueryOptions ops)` Perform a search specified in an HQL or SQL string.
`void` `setPersistenceOptions(PersistenceOptions ops)` Set options to control how objects are managed in the Hibernate session.
`void` `startTransaction()` Begin a transaction.
`<T extends SailPointObject> void` `unlockObject(T object)` Save and unlock an object.
`int` `update(java.lang.String query, java.util.Map<java.lang.String,java.lang.Object> args)`

### Methods inherited from interface sailpoint.object.Resolver

`getObject`

### Field Detail

#### LOCK_NAME

    static final java.lang.String LOCK_NAME

Option for lockObject that specifies the name of the user that will hold the lock.

See Also:
  Constant Field Values

#### LOCK_TYPE

    static final java.lang.String LOCK_TYPE

Option for lockObject that specifies the type of lock to be acquired. The default is a persistent lock.

See Also:
  Constant Field Values

#### LOCK_TYPE_TRANSACTION

    static final java.lang.String LOCK_TYPE_TRANSACTION

A value for the LOCK_TYPE option that selects a transaction lock. A transaction lock is held only for the duration of the current transaction, it corresponds to a Hibernate fetch with LockMode.UPGRADE, which in turn corresponds to a SQL select with the "for update" option. If another transaction has locked this object, the calling thread will suspend until the other transaction completes (or the request times out). This type of lock is appropriate for internal background tasks that need exclusive access to an object for a short duration and do not need the overhead of a persistent lock.

See Also:
  Constant Field Values

#### LOCK_TYPE_PERSISTENT

    static final java.lang.String LOCK_TYPE_PERSISTENT

A value for the LOCK_TYPE option that selects a persistent lock. A persistent lock is an application-level locking convention that uses a special column in the object table to indicate the lock status. A persistent lock can span transactions. Persistent locks are appropriate if you need to lock an object for a long period of time, or keep an object locked across a transaction boundary. This type of lock is most appropriate for editing sessions in the UI. Because it must modify the locked object it has more overhead than a transaction lock which makes it less suitable for background tasks that scan many objects.

See Also:
  Constant Field Values

### Method Detail

#### clone

    java.lang.Object clone()
                    throws java.lang.CloneNotSupportedException

Optional clone method. Not necessarily implemented.

Throws:
  `java.lang.CloneNotSupportedException`

#### startTransaction

    void startTransaction()
                   throws GeneralException

Begin a transaction. This is implicitly called before any other operation if the transaction has not yet been started.

Throws:
  `GeneralException`

#### commitTransaction

    void commitTransaction()
                    throws GeneralException

Commit the current transaction that was started with `startTransaction()`.

Throws:
  `GeneralException`

#### commitTransaction

    void commitTransaction(boolean startNewTransaction)
                    throws GeneralException

Commit the current transaction that was started with `startTransaction()`.

Throws:
  `GeneralException`

#### rollbackTransaction

    void rollbackTransaction()
                      throws GeneralException

Rollback the current transaction that was started with `startTransaction()`.

Throws:
  `GeneralException`

#### releasePersistentLocks

    void releasePersistentLocks()
                         throws GeneralException

Ensure any persistent locks acquired are released before releasing this context.

Throws:
  `GeneralException`

#### close

    void close()
        throws GeneralException

Close this PersistenceManager and release any resources in use. If there is an active transaction, this is rolled back. This is a package-protected method because it should only be called by `SailPointFactory.releaseContext()`.

Throws:
  `GeneralException`

#### getObjectById

    <T extends SailPointObject> T getObjectById(java.lang.Class<T> cls,
                                                java.lang.String id)
                                         throws GeneralException

Retrieve an object by id.

Specified by:
  `getObjectById` in interface `Resolver`
Throws:
  `GeneralException`

#### getObjectByName

    <T extends SailPointObject> T getObjectByName(java.lang.Class<T> cls,
                                                  java.lang.String name)
                                           throws GeneralException

Retrieve an object by name.

Specified by:
  `getObjectByName` in interface `Resolver`
Throws:
  `GeneralException`

#### lockObjectById

    <T extends SailPointObject> T lockObjectById(java.lang.Class<T> cls,
                                                 java.lang.String id,
                                                 java.util.Map<java.lang.String,java.lang.Object> options)
                                          throws GeneralException

Retrieve an object with a long-duration lock.

Throws:
  `GeneralException`

#### lockObjectByName

    <T extends SailPointObject> T lockObjectByName(java.lang.Class<T> cls,
                                                   java.lang.String name,
                                                   java.util.Map<java.lang.String,java.lang.Object> options)
                                            throws GeneralException

Retrieve an object with a long-duration lock.

Throws:
  `GeneralException`

#### unlockObject

    <T extends SailPointObject> void unlockObject(T object)
                                           throws GeneralException

Save and unlock an object. This will commit the transaction. Note that this method does not care who you are and if you hold the lock, it simply releases the current lock.

Throws:
  `GeneralException`

#### getUniqueObject

    <T extends SailPointObject> T getUniqueObject(T example)
                                           throws GeneralException

Retrieve an object whose properties match those specified in an example object. If more than one object match the criteria, null is returned. Note that this practically useless because if the class contains boolean or integer fields you have to set them, there is no "nullness" of primitive types that keeps them out of the criteria. For example searching for ManagedAttribute by value will fail to find anything with the "uncorrelated" property true.

Throws:
  `GeneralException`

#### getUniqueObject

    <T extends SailPointObject> T getUniqueObject(java.lang.Class<T> cls,
                                                  Filter f)
                                           throws GeneralException

Retrieve an object matching a Filter. If more than one object matches the filter null is returned.

Throws:
  `GeneralException`

#### saveObject

    void saveObject(SailPointObject obj)
             throws GeneralException

Save an object in the persistent store.

Throws:
  `GeneralException`

#### importObject

    void importObject(SailPointObject obj)
               throws GeneralException

Import an object into the persistent store. This is intended to be used only from the Importer. It differs from saveObject in that it will allow the overwriting of an existing object with the same name.

Throws:
  `GeneralException`

#### removeObject

    void removeObject(SailPointObject obj)
               throws GeneralException

Remove an object from the persistent store.

Throws:
  `GeneralException`

#### removeObjects

    <T extends SailPointObject> void removeObjects(java.lang.Class<T> cls,
                                                   QueryOptions ops)
                                            throws GeneralException

Bulk remove object based on the Filter defined in the QueryOptions.

Throws:
  `GeneralException`

#### getObjects

    <T extends SailPointObject> java.util.List<T> getObjects(java.lang.Class<T> cls)
                                                      throws GeneralException

Return all objects of a given class. Useful for things like Reports and JobSchedules, but be careful with objects that can have lots of instances.

Throws:
  `GeneralException`

#### getObjects

    <T extends SailPointObject> java.util.List<T> getObjects(java.lang.Class<T> cls,
                                                             QueryOptions ops)
                                                      throws GeneralException

Return all objects of a given class, constrained by Filters in the QueryOptions. Note that although you can specify them, Projections in the QueryOptions are not supported for this method. If you need to use Projections, use the search method.

Specified by:
  `getObjects` in interface `Resolver`
Throws:
  `GeneralException`

#### countObjects

    int countObjects(java.lang.Class cls,
                     QueryOptions options)
              throws GeneralException

Counts the number of objects that match a criteria.

Throws:
  `GeneralException`

#### search

    <T extends SailPointObject> java.util.Iterator<T> search(java.lang.Class<T> cls,
                                                             QueryOptions options)
                                                      throws GeneralException

Return a set of objects matching the query options. NOTE: Although this returns an iterator, implementations are actually fetching all the objects into memory so use this with care. OTHER NOTE: This non-projection variation of search() does not honor distinct=true on the QueryOptions. However, getObjects() does. Consider using that instead.

Throws:
  `GeneralException`
See Also:
  `getObjects(Class, QueryOptions)`

#### search

    <T extends SailPointObject> java.util.Iterator<java.lang.Object[]> search(java.lang.Class<T> cls,
                                                                              QueryOptions options,
                                                                              java.lang.String properties)
                                                                       throws GeneralException

Perform a projection search for selected object properties and return an iterator. Depending on the specific implementation this may or may not return an iterator that encapsulates a database cursor that will fetch gradually. User beware, and break large queries into chunks to avoid potential OOM errors. 10/2020********************************************************** NOTE THAT CURRENT MYSQL IMPLEMENTATIONS WILL GENERALLY PULL THE FULL RESULT SET INTO MEMORY. *** This is similar to `search(Class, QueryOptions, List)` but accepts the properties as a comma-separated string rather than a list.

Parameters:
  `cls` - The Class to search over.
  `options` - The QueryOptions to use.
  `properties` - A comma-separated list of properties to return.
Throws:
  `GeneralException`

#### search

    <T extends SailPointObject> java.util.Iterator<java.lang.Object[]> search(java.lang.Class<T> cls,
                                                                              QueryOptions options,
                                                                              java.util.List<java.lang.String> properties)
                                                                       throws GeneralException

Perform a projection search for selected object properties and return an iterator. Depending on the specific implementation this may or may not return an iterator that encapsulates a database cursor that will fetch gradually. User beware, and break large queries into chunks to avoid potential OOM errors. 10/2020********************************************************** NOTE THAT CURRENT MYSQL IMPLEMENTATIONS WILL GENERALLY PULL THE FULL RESULT SET INTO MEMORY. ***

Throws:
  `GeneralException`

#### requiresJoin

    boolean requiresJoin(java.lang.Class<? extends SailPointObject> cls,
                         QueryOptions options,
                         java.util.List<java.lang.String> properties)

Returns whether the resulting query for the specified QueryOptions and properties requires sql joins, making duplicate results possible.

Parameters:
  `cls` - The class that we're searching on.
  `options` - The QueryOptions with filters and ordering.
  `properties` - The List of properties to return.
Returns:
  whether the resulting query requires sql joins, making duplicate results possible.

#### getPropertyIterator

    default <T> java.util.Iterator<T> getPropertyIterator(java.lang.Class<? extends SailPointObject> cls,
                                                          QueryOptions options,
                                                          java.lang.String property)
                                                   throws GeneralException

Perform a projection search for a single object property and return an iterator. This is preferable over `getPropertyList(java.lang.Class<? extends sailpoint.object.SailPointObject>, sailpoint.object.QueryOptions, java.lang.String)` for large results to avoid pulling too much data into memory, but should not be used if the results need to be iterable across transaction boundaries, as the iterator session may be closed on commits.

Throws:
  `GeneralException`

#### getPropertyList

    default <T> java.util.List<T> getPropertyList(java.lang.Class<? extends SailPointObject> cls,
                                                  QueryOptions options,
                                                  java.lang.String property)
                                           throws GeneralException

Perform a projection search for a single object property and return a list. This should be used only when the results size is small or if the results need to be iterable across transaction boundaries. Otherwise `getPropertyIterator(java.lang.Class<? extends sailpoint.object.SailPointObject>, sailpoint.object.QueryOptions, java.lang.String)` should be used.

Throws:
  `GeneralException`

#### search

    java.util.Iterator search(java.lang.String query,
                              java.util.Map<java.lang.String,java.lang.Object> args,
                              QueryOptions ops)
                       throws GeneralException

Perform a search specified in an HQL or SQL string. By default the query string is parsed as HQL. If you want to use SQL, prefix the string with "sql:". What you get back from the iterator depends on the query. For HQL queries that return objects it will be an Iterator<SailPointObject>. For SQL queries or HQL queries that return projections it will be Iterator<Object[]>.

Throws:
  `GeneralException`

#### update

    int update(java.lang.String query,
               java.util.Map<java.lang.String,java.lang.Object> args)
        throws GeneralException

Parameters:
  `query` - It can be either hql or sql. If it is sql it should be prepended with "sql:"
  `args` - Parameters for the query
Returns:
  number of rows updated
Throws:
  `GeneralException`

#### attach

    void attach(SailPointObject object)
         throws GeneralException

Attach the given SailPointObject possibly loaded by a different SailPointContext to this SailPointContext.

Throws:
  `GeneralException`

#### decache

    void decache(SailPointObject obj)
          throws GeneralException

Remove the object from the cache. Necessary if you are processing large numbers of objects in the same session.

Throws:
  `GeneralException`

#### decache

    void decache()
          throws GeneralException

Remove all objects the cache.

Throws:
  `GeneralException`

#### setPersistenceOptions

    void setPersistenceOptions(PersistenceOptions ops)

Set options to control how objects are managed in the Hibernate session.

#### getPersistenceOptions

    PersistenceOptions getPersistenceOptions()

Get current options that control how objects are managed in the Hibernate session.

#### enableStatistics

    void enableStatistics(boolean b)

Enable or disable collection of statistics.

#### printStatistics

    void printStatistics()

Print the collected statistics.

#### reconnect

    void reconnect()

Reconnect the PersistenceManager to the persistent store (for example, by reconnecting to the database). This should almost never be used. Consider using `decache()` instead.

#### clearHighLevelCache

    void clearHighLevelCache()
                      throws GeneralException

Clears a "high level" cache. This method has the effect of removing objects from a cache (if one exists) that is above the session level. For Hibernate, this method clears the second level cache.

Throws:
  `GeneralException`

#### lockObject

    <T extends SailPointObject> T lockObject(java.lang.Class<T> clazz,
                                             PersistenceManager.LockParameters params)
                                      throws GeneralException

This method should be the entry point for all public locking calls. Other locking methods are there for backward compatibility and will delegate to this.

Parameters:
  `clazz` - The sailpoint class type of the object
  `params` - contains all the information pertinent to locking.
Returns:
  the locked object
Throws:
  `GeneralException`