net.java.ao.cache.Cache Maven / Gradle / Ivy
Show all versions of activeobjects Show documentation
/*
* Copyright 2007 Daniel Spiewak
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.java.ao.cache;
import net.java.ao.EntityManager;
import net.java.ao.RawEntity;
/**
* The super-interface for all value cache implementations. Implementations of
* this interface create an instance of {@link CacheLayer} for a given
* {@link RawEntity}. The design is such that any implementation of this interface
* acts as the primary controller for the cache, delegating entity-specific tasks
* to a custom implementation of CacheLayer. Any resources which are
* associated with a cache should be managed within the implementation of this
* interface.
*
* An example design would be for caching in a database (a patently useless
* operation, given the function of the framework). In this cache, the database
* itself would be managed in the implementation of ValueCache. This
* class would then instantiate instances of a custom CacheLayer
* implementation which would handle the actual act of caching data for specific
* RawEntity instances (most likely each corresponding with a single
* row). By separating these implementations, it is possible keep resources
* handled in a central controller while still devoting distinct memory space to
* specific entities. The distinct memory is most important in the default
* implementation, {@link RAMCache}.
*
* Generically, implementations of ValueCache function as a
* factory and controller for the relevant implementation of CacheLayer.
* The primary purpose is to construct new instances of the implementation-specific
* CacheLayer and to manage resources common to all constructed
* instances.
*
* @author Daniel Spiewak
* @see #createCacheLayer(RawEntity)
* @see EntityManager#setCache(Cache)
* @see EntityManager#getCache()
*/
public interface Cache {
/**
* Retrieves a CacheLayer instance which corresponds to the given
* entity. CacheLayer instance(s) may themselves be cached within
* the value cache, but this is not part of the specification. Generically,
* this method should return an instance of a working CacheLayer
* implementation which can persist values relevant to the given entity in an
* implementation-specific way. For example, the default implementation of this
* interface ({@link RAMCache}) returns a CacheLayer which can
* cache values in memory for a specific entity.
*
* Typically, instances of the same implementation are returned for any
* given entity (e.g. RAMCacheLayer always returns an instance of
* RAMValueCache, regardless of the entity in question). It is
* theoretically possible however to differentiate layers based on entity type
* or even specific primary key value. I'm not sure why you would want to do
* this, but there's nothing in the requirements which would prevent it. Code
* which uses the result of this method should certainly be written to the
* interface, rather than any specific implementation.
* @param entity TODO
*
* @return A layer which will handle caching of values as necessary for the
* given entity.
*/
public CacheLayer createCacheLayer(RawEntity entity);
public RelationsCache getRelationsCache();
/**
* Frees all resources associated with the cache. This should be used to
* handle things like closing connections, freeing result-sets, etc. This
* method will be called by {@link EntityManager} on the old ValueCache
* when a new instance is specified.
*
* @see EntityManager#setCache(Cache)
*/
public void dispose();
}