/* Open Source Java Caching Service
* Copyright (C) 2002 Frank Karlstr�m
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* The author can be contacted by email: fjankk@users.sourceforge.net
*/
package javax.util.jcache;
import java.io.File;
import java.io.OutputStream;
import java.io.Serializable;
import org.fjank.jcache.CacheImpl;
import org.fjank.jcache.CacheObject;
import org.fjank.jcache.CacheRegion;
import org.fjank.jcache.StreamCacheObject;
/**
* This class loads object into the cache with the aid of the abstract load
* method. Should be extended by the user to implement custom loaders, such as
* Database queries, Directory searches, File extraction, Net searches etc.
* @deprecated Will be removed and replaced with an interface.
* @author Frank Karlstr�m
*/
public abstract class CacheLoader implements Serializable {
/**
* this method must be implemented by the user to load objects into the
* cache. This will typically be a database-call or directory call, or
* extracting information from a file. This method returns a reference to
* the newly loaded object. If the object being loaded is a StreamAccess
* object or a disk object, the OutputStream object created by the
* createStream method, or the File created by the createDiskObject method
* should be returned.
*
* @param handle is supplied by the cache and is used by the netSearch and
* setAttributes methods to access information about the object
* being searched for.
* @param arguments is the object pass to the cache in the get method.
*
* @return a reference to the newly created object.
*/
public abstract Object load(final Object handle, final Object arguments)
throws CacheException;
/**
* will cause the attributes associated with the object being loaded to be
* set to values provided in attributes. If the attributes is null,
* default attributes are assumed.
*
* @param handle handle is the object passed into the load method.
* @param attributes the attributes to set.
*
* @throws CacheException if an error occurs.
*/
public final void setAttributes(final Object handle,
final Attributes attributes) throws CacheException {
CacheObject cacheObj = convertHandle(handle);
if (attributes == null) {
cacheObj.setAttributes(CacheAccessFactory.getInstance().getDefaultAttributes());
} else {
cacheObj.setAttributes(attributes);
}
}
/**
* Will validate an handle and return the correct class for this Object.
*
* @param handle the handle to convert.
*
* @return the handle converted to a CacheObject
*
* @throws InvalidArgumentException of the handle is not an instance of a
* CacheObject
*/
private CacheObject convertHandle(final Object handle)
throws InvalidArgumentException {
if (handle == null) {
throw new InvalidArgumentException(
"The handle passed in to this method was null.");
}
if (!(handle instanceof CacheObject)) {
throw new InvalidArgumentException(
"The handle was not a valid CacheObject.");
}
CacheObject cacheObj = ((CacheObject) handle);
return cacheObj;
}
/**
* returns the name associated with object being loaded. This method is
* only available to be called by application overrides of the load
* method.
*
* @param handle the handle to the object being loaded.
*
* @return the name associated with the object being loaded.
*
* @throws CacheException if some strange unexpected exception occur.
*/
protected final Object getName(final Object handle)
throws CacheException {
return convertHandle(handle).getKey();
}
/**
* return the name of the region for the object being loaded. This method
* is only available to be called from applications overriding the load
* method.
*
* @param handle the handle to the object being loaded.
*
* @return the region for the object being loaded.
*
* @throws CacheException if strange unexpected exceptions occur.
* @throws NullObjectException if an object is discovered with required
* variables which is null.
*/
protected final String getRegion(final Object handle)
throws CacheException {
final CacheObject cacheObj = convertHandle(handle);
final CacheRegion region = cacheObj.getRegion();
if (region == null) {
throw new NullObjectException("The object " + cacheObj
+ " is not attached to a region.");
}
final Object name = region.getName();
if (name != null) {
return name.toString();
} else {
return null;
}
}
/**
* will search other caches for the object to be loaded. This method is
* only available to be called from applications overriding the load
* method. If the search is successfull, a reference to a local copy of
* the object is returned.
*
* @param handle the handle to the object being created.
* @param timeout the net search timeout.
*
* @return a reference to a local copy of the object.
*
* @throws CacheException if a timeout occurs, or the object is not found.
* @throws NotImplementedException will always be thrown
*
* @todo implement distribution.
*/
protected final Object netSearch(final Object handle, final int timeout)
throws CacheException {
throw new NotImplementedException();
}
/**
* should be called from the load method to create a StreamAccess object.
* The OutputStream returned is used to load the object into the cache.
* Default attributes are used. ObjectExistsExceptions occuring during
* this call can either be propagated to the caller , or null is returned.
* In both cases the cache will recognize that the object has been loaded
* by another cache, and return the object to the user.
*
* @param handle the object passed into the load method.
*
* @return an OutputStream to read the object into the cache.
*
* @throws ObjectExistsException if the object is declared as distributed,
* and another cache is in the progress of loading.
* @throws InvalidArgumentException if some of the arguments are not valid
* in this context
*/
public final OutputStream createStream(final Object handle)
throws ObjectExistsException, InvalidArgumentException {
CacheObject co = convertHandle(handle);
try {
StreamCacheObject str =
new StreamCacheObject(co.getKey(), null, co.getGroup(),
co.getRegion(), CacheImpl.getCache(true).getReferenceQueue());
return str.getOutputStream();
} catch (CacheNotAvailableException e) {
throw new InvalidArgumentException("The cache is not available.");
} catch (CacheException e) {
throw new InvalidArgumentException(
"The cache is not available, as an error occured."
+ e.getMessage());
}
}
/**
* should be called from the load method to create a StreamAccess object.
* The OutputStream returned is used to load the object into the cache.
* Default attributes are used. ObjectExistsExceptions occuring during
* this call can either be propagated to the caller , or null is returned.
* In both cases the cache will recognize that the object has been loaded
* by another cache, and return the object to the user.
*
* @param handle the object passed into the load method.
* @param attributes the attributes will be set on the object by this
* method. If null, default attributes are used.
*
* @return an OutputStream to read the object into the cache.
*
* @throws CacheException if the object is declared as distributed, and
* another cache is in the progress of loading, or any other
* strange exceptions occurs.
*/
public final OutputStream createStream(final Object handle,
final Attributes attributes) throws CacheException {
setAttributes(handle, attributes);
return createStream(handle);
}
/**
* is called from the load object to create a disk object. The File
* returned can then be used to load the object into the cache.
* ObjectExistsExceptions occuring during this call can either be
* propagated to the caller , or null is returned. In both cases the cache
* will recognize that the object has been loaded by another cache, and
* return the object to the user.
*
* @param handle the object passed into the load method.
* @param extension The extension parameter is used as the extension to the
* file name (java, class, exe etc.) If null, no extension is
* added.
*
* @return a File which represent the object being created.
*
* @throws CacheException if the object is declared as distributed, and
* another cache is in the progress of loading, or any other
* strange exceptions occurs.
*/
public final File createDiskObject(final Object handle,
final String extension) throws CacheException {
CacheObject cacheObj = convertHandle(handle);
CacheAttributes att = getCacheAttributes();
String rootPath = att.getDiskPath();
String ext;
if (extension == null) {
ext = "";
} else {
ext = '.' + extension;
}
return new File(rootPath + File.separatorChar + cacheObj.getKey() + ext);
}
/**
* DOCUMENT ME!
*
* @return DOCUMENT ME!
*
* @throws CacheNotAvailableException DOCUMENT ME!
* @throws CacheException DOCUMENT ME!
*/
private CacheAttributes getCacheAttributes()
throws CacheNotAvailableException, CacheException {
CacheAccessFactory fact = CacheAccessFactory.getInstance();
Cache cache = fact.getCache();
return cache.getAttributes();
}
/**
* is called from the load object to create a disk object. The File
* returned can then be used to load the object into the cache.
* ObjectExistsExceptions occuring during this call can either be
* propagated to the caller , or null is returned. In both cases the cache
* will recognize that the object has been loaded by another cache, and
* return the object to the user.
*
* @param handle the object passed into the load method.
* @param attributes the attributes will be set on the object by this
* method. If null, default attributes are used.
* @param extension The extension parameter is used as the extension to the
* file name (java, class, exe etc.) If null, no extension is
* added.
*
* @return a File wich represent the object being created.
*
* @throws CacheException if the object is declared as distributed, and
* another cache is in the progress of loading, or any other
* strange exceptions occurs.
*/
public final File createDiskObject(final Object handle,
final Attributes attributes, final String extension)
throws CacheException {
setAttributes(handle, attributes);
return createDiskObject(handle, extension);
}
/**
* is called from the load method to record a message in the cache's log.
* How and where the logging occurs is dependent if the configuration of
* the logger in the cache.
*
* @param msg the message to log.
*
* @todo implement this method.
*/
public final void log(final String msg) {
try {
CacheAttributes cacheAttributes = getCacheAttributes();
CacheLogger logger = cacheAttributes.getLogger();
logger.log(msg);
} catch (CacheNotAvailableException e) {
//doh, how did we get here then?
} catch (CacheException e) {
//doh, what now?
}
}
/**
* this method is called from the load method to convert any non
* CacheExceptions into CacheExceptions, with the base exception set to
* the original exception. This allows the load method to only throw
* CacheExceptions without loosing important information. The exception
* will also be logged assuming the logging is configured and the logging
* severity is set sufficently high. For all CacheExceptions, if
* CacheException.printStackTrace() is called, and there is a base
* exception, the stack for the base will be printed.
*
* @param msg a message to provide to the CacheException.
* @param exception the Exception to be wrapped. If null, a default
* CacheException is returned.
*
* @return a CacheException wrapping the exception.
*/
public final CacheException exceptionHandler(final String msg,
final Exception exception) {
return new CacheException(msg, exception);
}
}