at.spardat.xma.boot.cache.IFileCache Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2003, 2007 s IT Solutions AT Spardat GmbH .
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* s IT Solutions AT Spardat GmbH - initial API and implementation
*******************************************************************************/
package at.spardat.xma.boot.cache;
import java.io.File;
import java.io.IOException;
import java.net.URL;
import at.spardat.xma.boot.comp.data.XMAResource;
import at.spardat.xma.boot.component.IRtXMASessionClient;
import at.spardat.xma.boot.transport.XMA_URI;
/**
* Interface to the file cache. Users of the file cache should always use it through this
* interface to stay apart of implementation details.
*
* @author s3595 Chris Sch?fer (CGS)
* @version $Id: IFileCache.java 2084 2007-11-27 14:53:31Z s3460 $
*/
public interface IFileCache {
/**
* This method will open a resource represented by a valid {@link URL}.
* Same as {@link #openResource(URL, boolean, boolean, IRtXMASessionClient)} called
* with (urlRemote, true, false, null).
* @param urlRemote remote url to open.
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
*
*/
public abstract IFileCacheResource openResource(URL urlRemote)
throws IOException;
/**
* This method will open a resource represented by a valid {@link URL}.
* Same as {@link #openResource(URL, boolean, boolean, IRtXMASessionClient)} called
* with (urlRemote, true, false, session).
*
* @param session xma session (or null)
* @param urlRemote remote url to open.
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
*/
public abstract IFileCacheResource openResource(IRtXMASessionClient session, URL urlRemote)
throws IOException;
/**
* This method will open a resource represented by a valid {@link URL}.
* Same as {@link #openResource(URL, boolean, boolean, IRtXMASessionClient)} called
* with (urlRemote, bmode, bforce, null).
*
* @param urlRemote remote url to open.
* @param bmode use true for buffered mode.
* @param bforce force an update check with the server
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
*/
public abstract IFileCacheResource openResource(URL urlRemote, boolean bmode, boolean bforce)
throws IOException;
/**
* This method will open a resource represented by a valid {@link URL}.
* Same as {@link #openResource(URL, boolean, boolean, IRtXMASessionClient)} called
* with (urlRemote, bmode, false, null).
*
* @param urlRemote remote url to open.
* @param bmode use true for buffered mode.
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
*/
public abstract IFileCacheResource openResource(URL urlRemote, boolean bmode )
throws IOException;
/**
* This method will open a resource represented by a valid {@link URL}.
* The method returns a memory copy of the underlying file resource.
* A resource is valid for the cache, if it is not expired yet. That means, that
* its expiration timestamp has not been reached yet, or there is none.
* In buffered mode (bmode=true), the resource reads the cache entry, into a memory buffer
* imediately on object creation. In non buffered mode, the buffer is created
* on first access.
*
*
* -
* If the resource is cached and still valid, the cached copy is returned as is.
*
-
* If the resource is not cached or is not valid any more, a new copy is loaded.
*
*
*
* @param urlRemote remote url to open.
* @param bmode read the cache entry, into a memory buffer imediately on object creation
* @param bforce force an update check with the server
* @param session xma session (or null)
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
*/
public IFileCacheResource openResource( URL urlRemote, boolean bmode, boolean bforce, IRtXMASessionClient session )
throws IOException;
/**
* This method will open a resource represented by a valid {@link XMAResource}.
* The method returns a memory copy of the underlying file resource.
* The resouce is only valid, if the version hash of the {@link XMAResource} match the
* hash of the cached resource.
*
*
* -
* If the resource is cached and still valid, the cached copy is returned as is.
*
-
* If the resource is not cached or is not valid any more, a new copy is loaded.
*
*
*
* @param appUri uri of the xma application
* @param resource the wanted resource inside this application
* @param serverVers version number of the xma-runtime on the server
* @param bforce force an update check with the server
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
* @since 1.3.0
* @author s2877
*/
public IFileCacheResource openResource(XMA_URI appUri, XMAResource resource, VersionNumber serverVers, boolean bforce) throws IOException;
/**
* This method will open a resource represented by a valid {@link XMA_URI}.
* The method returns a memory copy of the underlying file resource.
* The resouce is only valid, if the given hash match the hash value of the cached resource.
*
*
* -
* If the resource is cached and still valid, the cached copy is returned as is.
*
-
* If the resource is not cached or is not valid any more, a new copy is loaded.
*
*
*
* @param resource the wanted resource
* @param hash the expected hash value of the resouce
* @param serverVers version number of the xma-runtime on the server
* @param bforce force an update check with the server
* @return IFileCacheResource the cached resource
*
* @throws IOException on filesystem errors
* @throws CommunicationException communication error with server
* @throws ServerException on server exception
* @throws IllegalArgumentException prepare a valid url
* @since 1.3.0
* @author s2877
*/
public IFileCacheResource openResource(XMA_URI resource,String hash,VersionNumber serverVers,boolean bforce) throws IOException;
/**
* Open a resource from the local cache. No effort is made to download it, if it is not
* cached null is returned. The resource is not checked for expiration or integrity.
* This method does not find shared resources.
* @param resource to open
* @return the resource from the local cache or null if not cached.
* @throws IOException containing the filename on filesystem errors
* @since 1.3.0
* @author s2877
*/
public IFileCacheResource openLocalResource(XMA_URI resource);
/**
* invalidates a cache-entry if exists
*
* will invalidate all file-resources from the file cache directory for this url.
*
* If the resource is not found/is not cached, no error is reported.
*
* @param urlRemote the remote url that is the key to the cached resources
* @throws IOException on file errors
*/
public abstract void invalidateResource(URL urlRemote) throws IOException;
/**
* call this method to remove (delete) all information of this cached resource.
*
* @param ifcr the resource to invalidate
*/
public abstract void invalidateResource(IFileCacheResource ifcr);
/**
* Check if there is allready a local copy of this remote URL.
* It does not check, wheather the local copy is expired.
*
* @param urlRemote remote URL to check for a local cached copy
* @return returns true if the resource is cached
*
* @throws IllegalArgumentException if the source is not cacheable
*/
public abstract boolean isCached(URL urlRemote);
/**
* Get the directory where the file cache is located.
* @since 1.3.0
* @author s2877
*/
public File getBaseDir();
/**
* Check if there is allready a local copy of the given resouce.
* It checks if the resource is not expired and the stored hash value
* matches the given hash.
* @param uri defining the resource
* @param hash expected hash value of the resource
* @return true if the resoure is cached an valid according to hash and expiration.
* @throws IOException
* @since 1.3.0
* @author s2877
*/
public boolean isCachedAndValid(XMA_URI uri,String hash) throws IOException;
/**
* Check if there is allready a local copy of the given resouce.
* It checks if the resource is not expired and the stored hash value
* matches the given hash.
* @param resource to check
* @param hash expected hash value of the resource
* @return true if the resoure is cached an valid according to hash and expiration.
* @throws IOException
* @since 1.3.0
* @author s2877
*/
public boolean isCachedAndValid(IFileCacheResource resource,String hash);
/**
* Check the integrity of the given resource.
* The given hash value is compared to the stored hash value of the resource. Additionally
* the hash value is calculated from the resource and compared. This does not only detect
* a wrong version of the resource. It detects corrupted and manipulated resources, too.
* @param resource to check
* @param hash expected hash value
* @param isJar if the resource is a jar file or not
* @return true if the hash matches, false otherwise
* @since 1.3.0
* @author s2877
*/
public boolean checkHash(IFileCacheResource resource, String hash, boolean isJar);
}