at.spardat.xma.boot.cache
Interface IFileCache

All Known Implementing Classes:
FileCache

public interface IFileCache

Interface to the file cache. Users of the file cache should always use it through this interface to stay apart of implementation details.


Method Summary
 boolean checkHash(IFileCacheResource resource, java.lang.String hash, boolean isJar)
          Check the integrity of the given resource.
 java.io.File getBaseDir()
          Get the directory where the file cache is located.
 void invalidateResource(IFileCacheResource ifcr)
          call this method to remove (delete) all information of this cached resource.
 void invalidateResource(java.net.URL urlRemote)
          invalidates a cache-entry if exists will invalidate all file-resources from the file cache directory for this url.
 boolean isCached(java.net.URL urlRemote)
          Check if there is allready a local copy of this remote URL.
 boolean isCachedAndValid(IFileCacheResource resource, java.lang.String hash)
          Check if there is allready a local copy of the given resouce.
 boolean isCachedAndValid(XMA_URI uri, java.lang.String hash)
          Check if there is allready a local copy of the given resouce.
 IFileCacheResource openLocalResource(XMA_URI resource)
          Open a resource from the local cache.
 IFileCacheResource openResource(IRtXMASessionClient session, java.net.URL urlRemote)
          This method will open a resource represented by a valid URL.
 IFileCacheResource openResource(java.net.URL urlRemote)
          This method will open a resource represented by a valid URL.
 IFileCacheResource openResource(java.net.URL urlRemote, boolean bmode)
          This method will open a resource represented by a valid URL.
 IFileCacheResource openResource(java.net.URL urlRemote, boolean bmode, boolean bforce)
          This method will open a resource represented by a valid URL.
 IFileCacheResource openResource(java.net.URL urlRemote, boolean bmode, boolean bforce, IRtXMASessionClient session)
          This method will open a resource represented by a valid URL.
 IFileCacheResource openResource(XMA_URI resource, java.lang.String hash, VersionNumber serverVers, boolean bforce)
          This method will open a resource represented by a valid XMA_URI.
 IFileCacheResource openResource(XMA_URI appUri, XMAResource resource, VersionNumber serverVers, boolean bforce)
          This method will open a resource represented by a valid XMAResource.
 

Method Detail

openResource

public IFileCacheResource openResource(java.net.URL urlRemote)
                                throws java.io.IOException
This method will open a resource represented by a valid URL.
Same as openResource(URL, boolean, boolean, IRtXMASessionClient) called with (urlRemote, true, false, null).

Parameters:
urlRemote - remote url to open.
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url

openResource

public IFileCacheResource openResource(IRtXMASessionClient session,
                                       java.net.URL urlRemote)
                                throws java.io.IOException
This method will open a resource represented by a valid URL.
Same as openResource(URL, boolean, boolean, IRtXMASessionClient) called with (urlRemote, true, false, session).

Parameters:
session - xma session (or null)
urlRemote - remote url to open.
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url

openResource

public IFileCacheResource openResource(java.net.URL urlRemote,
                                       boolean bmode,
                                       boolean bforce)
                                throws java.io.IOException
This method will open a resource represented by a valid URL.
Same as openResource(URL, boolean, boolean, IRtXMASessionClient) called with (urlRemote, bmode, bforce, null).

Parameters:
urlRemote - remote url to open.
bmode - use true for buffered mode.
bforce - force an update check with the server
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url

openResource

public IFileCacheResource openResource(java.net.URL urlRemote,
                                       boolean bmode)
                                throws java.io.IOException
This method will open a resource represented by a valid URL.
Same as openResource(URL, boolean, boolean, IRtXMASessionClient) called with (urlRemote, bmode, false, null).

Parameters:
urlRemote - remote url to open.
bmode - use true for buffered mode.
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url

openResource

public IFileCacheResource openResource(java.net.URL urlRemote,
                                       boolean bmode,
                                       boolean bforce,
                                       IRtXMASessionClient session)
                                throws java.io.IOException
This method will open a resource represented by a valid 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.

Parameters:
urlRemote - remote url to open.
bmode - read the cache entry, into a memory buffer imediately on object creation
bforce - force an update check with the server
session - xma session (or null)
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url

openResource

public IFileCacheResource openResource(XMA_URI appUri,
                                       XMAResource resource,
                                       VersionNumber serverVers,
                                       boolean bforce)
                                throws java.io.IOException
This method will open a resource represented by a valid XMAResource.
The method returns a memory copy of the underlying file resource.
The resouce is only valid, if the version hash of the XMAResource match the hash of the cached resource.

Parameters:
appUri - uri of the xma application
resource - the wanted resource inside this application
serverVers - version number of the xma-runtime on the server
bforce - force an update check with the server
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url
Since:
1.3.0

openResource

public IFileCacheResource openResource(XMA_URI resource,
                                       java.lang.String hash,
                                       VersionNumber serverVers,
                                       boolean bforce)
                                throws java.io.IOException
This method will open a resource represented by a valid 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.

Parameters:
resource - the wanted resource
hash - the expected hash value of the resouce
serverVers - version number of the xma-runtime on the server
bforce - force an update check with the server
Returns:
IFileCacheResource the cached resource
Throws:
java.io.IOException - on filesystem errors
CommunicationException - communication error with server
ServerException - on server exception
java.lang.IllegalArgumentException - prepare a valid url
Since:
1.3.0

openLocalResource

public IFileCacheResource openLocalResource(XMA_URI resource)
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.

Parameters:
resource - to open
Returns:
the resource from the local cache or null if not cached.
Throws:
java.io.IOException - containing the filename on filesystem errors
Since:
1.3.0

invalidateResource

public void invalidateResource(java.net.URL urlRemote)
                        throws java.io.IOException

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.

Parameters:
urlRemote - the remote url that is the key to the cached resources
Throws:
java.io.IOException - on file errors

invalidateResource

public void invalidateResource(IFileCacheResource ifcr)
call this method to remove (delete) all information of this cached resource.

Parameters:
ifcr - the resource to invalidate

isCached

public boolean isCached(java.net.URL urlRemote)
Check if there is allready a local copy of this remote URL.
It does not check, wheather the local copy is expired.

Parameters:
urlRemote - remote URL to check for a local cached copy
Returns:
returns true if the resource is cached
Throws:
java.lang.IllegalArgumentException - if the source is not cacheable

getBaseDir

public java.io.File getBaseDir()
Get the directory where the file cache is located.

Since:
1.3.0

isCachedAndValid

public boolean isCachedAndValid(XMA_URI uri,
                                java.lang.String hash)
                         throws java.io.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.

Parameters:
uri - defining the resource
hash - expected hash value of the resource
Returns:
true if the resoure is cached an valid according to hash and expiration.
Throws:
java.io.IOException
Since:
1.3.0

isCachedAndValid

public boolean isCachedAndValid(IFileCacheResource resource,
                                java.lang.String hash)
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.

Parameters:
resource - to check
hash - expected hash value of the resource
Returns:
true if the resoure is cached an valid according to hash and expiration.
Throws:
java.io.IOException
Since:
1.3.0

checkHash

public boolean checkHash(IFileCacheResource resource,
                         java.lang.String hash,
                         boolean isJar)
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.

Parameters:
resource - to check
hash - expected hash value
isJar - if the resource is a jar file or not
Returns:
true if the hash matches, false otherwise
Since:
1.3.0