Ice Reference Documentation
<<< Previous | Slice Documentation | Next >>>

# `Freeze::Evictor`

## Overview

    local interface Evictor
        extends
    	::Ice::ServantLocator

An automatic Ice object persistence manager, based on the evictor pattern. The evictor is a servant locator implementation that stores the persistent state of its objects in a database. Any number of objects can be registered with an evictor, but only a configurable number of servants are active at a time. These active servants reside in a queue; the least recently used servant in the queue is the first to be evicted when a new servant is activated.

### See Also

`ServantInitializer`

### Operation Index

`add`

  Add a servant to this evictor.

`addFacet`

  Like `add`, but with a facet.

`createObject`

  Add or update a servant.

`destroyObject`

  Permanently destroy an Ice object.

`getIterator`

  Get an iterator for the identities managed by the evictor.

`getSize`

  Get the size of the evictor's servant queue.

`hasFacet`

  Like `hasObject`, but with a facet.

`hasObject`

  Returns true if the given identity is managed by the evictor with the default facet.

`keep`

  Lock this object in the evictor cache.

`keepFacet`

  Like `keep`, but with a facet.

`release`

  Release a "lock" acquired by `keep`.

`releaseFacet`

  Like `release`, but with a facet.

`remove`

  Permanently destroy an Ice object.

`removeFacet`

  Like `remove`, but with a facet.

`setSize`

  Set the size of the evictor's servant queue.

## `add`

    Object* add(Object servant,
        ::Ice::Identity id);

Add a servant to this evictor. The state of the servant passed to this operation will be saved in the evictor's persistent store.

### Parameters

`servant`

  The servant to add.

`id`

  The identity of the Ice object that is implemented by the servant.

### Return Value

A proxy that matches the given identity and this evictor's object adapter.

### Exceptions

`AlreadyRegisteredException`

  Raised if the evictor already has an object with this identity.

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`addFacet`, `remove`, `removeFacet`

## `addFacet`

    Object* addFacet(Object servant,
        ::Ice::Identity id,
        string facet);

Like `add`, but with a facet. Calling `add(servant, id)` is equivalent to calling `addFacet` with an empty facet.

### Parameters

`servant`

  The servant to add.

`id`

  The identity of the Ice object that is implemented by the servant.

`facet`

  The facet. An empty facet means the default facet.

### Return Value

A proxy that matches the given identity and this evictor's object adapter.

### Exceptions

`AlreadyRegisteredException`

  Raised if the evictor already has an object with this identity.

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`add`, `remove`, `removeFacet`

## `createObject`

    void createObject(::Ice::Identity id,
        Object servant);

Add or update a servant. The state of the servant passed to this operation will be saved in the evictor's persistent store. This operation is deprecated and will be removed in a future release. It is recommended to use add instead.

### Parameters

`id`

  The identity of the Ice object that is implemented by the servant.

`servant`

  The servant to add.

### Exceptions

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`add`, `destroyObject`

## `destroyObject`

    void destroyObject(::Ice::Identity id);

Permanently destroy an Ice object. Like remove, except destroyObject does not raise any exception when the object does not exist. This operation is deprecated and will be removed in a future release. It is recommended to use remove instead.

### Parameters

`id`

  The identity of the Ice object.

### Exceptions

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`remove`, `createObject`

## `getIterator`

    EvictorIterator getIterator(string facet,
        int batchSize);

Get an iterator for the identities managed by the evictor.

### Parameters

`facet`

  The facet. An empty facet means the default facet.

`batchSize`

  Internally, the Iterator retrieves the identities in batches of size batchSize. Selecting a small batchSize can have an adverse effect on performance.

### Return Value

A new iterator.

### Exceptions

`EvictorDeactivatedException`

  Raised if a the evictor has been deactivated.

## `getSize`

    int getSize();

Get the size of the evictor's servant queue.

### Return Value

The size of the servant queue.

### Exceptions

`EvictorDeactivatedException`

  Raised if a the evictor has been deactivated.

### See Also

`setSize`

## `hasFacet`

    bool hasFacet(::Ice::Identity id,
        string facet);

Like `hasObject`, but with a facet. Calling `hasObject(id)` is equivalent to calling `hasFacet` with an empty facet.

### Return Value

true if the identity is managed by the evictor for the given facet, false otherwise.

### Exceptions

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if a the evictor has been deactivated.

## `hasObject`

    bool hasObject(::Ice::Identity id);

Returns true if the given identity is managed by the evictor with the default facet.

### Return Value

true if the identity is managed by the evictor, false otherwise.

### Exceptions

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if a the evictor has been deactivated.

## `keep`

    void keep(::Ice::Identity id);

Lock this object in the evictor cache. This lock can be released by `release` or remove. `release` releases only one lock, while `remove` releases all the locks.

### Parameters

`id`

  The identity of the Ice object.

### Exceptions

`NotRegisteredException`

  Raised if this identity was not registered with the evictor.

`DatabaseException`

  Raised if a database failure occurred.

### See Also

`keepFacet`, `release`, `remove`

## `keepFacet`

    void keepFacet(::Ice::Identity id,
        string facet);

Like `keep`, but with a facet. Calling `keep(id)` is equivalent to calling `keepFacet` with an empty facet.

### Parameters

`id`

  The identity of the Ice object.

`facet`

  The facet. An empty facet means the default facet.

### Exceptions

`NotRegisteredException`

  Raised if this identity was not registered with the evictor.

`DatabaseException`

  Raised if a database failure occurred.

### See Also

`keep`, `releaseFacet`, `removeFacet`

## `release`

    void release(::Ice::Identity id);

Release a "lock" acquired by `keep`. Once all the locks on an object have been released, the object is again subject to the normal eviction strategy.

### Parameters

`id`

  The identity of the Ice object.

### Exceptions

`NotRegisteredException`

  Raised if this object was not "locked" with `keep` or `keepFacet`.

### See Also

`keepFacet`, `release`

## `releaseFacet`

    void releaseFacet(::Ice::Identity id,
        string facet);

Like `release`, but with a facet. Calling `release(id)` is equivalent to calling `releaseFacet` with an empty facet.

### Parameters

`id`

  The identity of the Ice object.

`facet`

  The facet. An empty facet means the default facet.

### Exceptions

`NotRegisteredException`

  Raised if this object was not "locked" with `keep` or `keepFacet`.

### See Also

`keep`, `releaseFacet`

## `remove`

    Object remove(::Ice::Identity id);

Permanently destroy an Ice object.

### Parameters

`id`

  The identity of the Ice object.

### Return Value

The removed servant.

### Exceptions

`NotRegisteredException`

  Raised if this identity was not registered with the evictor.

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`add`, `removeFacet`

## `removeFacet`

    Object removeFacet(::Ice::Identity id,
        string facet);

Like `remove`, but with a facet. Calling `remove(id)` is equivalent to calling `removeFacet` with an empty facet.

### Parameters

`id`

  The identity of the Ice object.

`facet`

  The facet. An empty facet means the default facet.

### Return Value

The removed servant.

### Exceptions

`NotRegisteredException`

  Raised if this identity was not registered with the evictor.

`DatabaseException`

  Raised if a database failure occurred.

`EvictorDeactivatedException`

  Raised if the evictor has been deactivated.

### See Also

`remove`, `addFacet`

## `setSize`

    void setSize(int sz);

Set the size of the evictor's servant queue. This is the maximum number of servants the evictor keeps active. Requests to set the queue size to a value smaller than zero are ignored.

### Parameters

`sz`

  The size of the servant queue. If the evictor currently holds more than `setSize` servants in its queue, it evicts enough servants to match the new size. Note that this operation can block if the new queue size is smaller than the current number of servants that are servicing requests. In this case, the operation waits until a sufficient number of servants complete their requests.

### Exceptions

`EvictorDeactivatedException`

  Raised if a the evictor has been deactivated.

### See Also

`getSize`

<<< Previous | Home | Next >>>
`Freeze::DeadlockException` | Up | `Freeze::EvictorDeactivatedException`