net.sf.mmm.util.resource.base

Class ClasspathResource

java.lang.Object

net.sf.mmm.util.resource.base.AbstractDataResource

net.sf.mmm.util.resource.base.ClasspathResource

All Implemented Interfaces:

DataResource

public class ClasspathResource
extends AbstractDataResource

This is the implementation of the DataResource interface for a resource that comes from the classpath.
A very nice feature of Java is to load resources from the classpath. This allows that these resource are deployed within a jar-file. Adding a directory to the beginning of the classpath still allows to override such a resource.
Anyways a typical mistake is illustrated by the following code example:

 MyClass.class.getResourceAsStream("config.xml")
 

This will NOT allow to override resources in other classpath entries and especially NOT work in situations where there are specific classloaders, what is a typical situation in environments of applications servers or IoC frameworks.
The solution is to use the context-class-loader to get resources what is done by this implementation. A proper version of the example above is:

 DataResource resource = ClasspathResource((MyClass.class.getPackage(), "config.xml"));
 if (!resource.isAvailable()) {
   // possible fallback
   resource = getFallbackResource();
 }
 InputStream inStream = resource.openStream();
 ...
 

Since:

1.0.2

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
private String	path
static String	SCHEME_PREFIX The scheme-prefix for this type of DataResource.
private URL	url

Constructor Summary

Constructors

Constructor and Description
ClasspathResource(Class<?> someClass, String nameOrSuffix, boolean append) The constructor for a classpath-resource identified by someClass and the given nameOrSuffix.
ClasspathResource(Package somePackage, String filename) The constructor.
ClasspathResource(String absoluteClasspath) The constructor.

Method Summary

Modifier and Type	Method and Description
private static String	getAbsolutePath(Class<?> someClass, String nameOrSuffix, boolean append)
Date	getLastModificationDate() This method gets the last modification date of the DataResource if available and supported.
String	getPath() This method gets the path of this resource.
String	getSchemePrefix() This method gets the scheme-prefix of absolute URIs for this type of DataResource.
String	getUri() This method gets a string identifying this DataResource.
URL	getUrl() This method gets this resource as URL.
boolean	isData() This method determines if this resource has potentially data available.
DataResource	navigate(String resourcePath) This method retrieves a DataResource pointing to the given resourcePath based on this resource. E.g.

Methods inherited from class net.sf.mmm.util.resource.base.AbstractDataResource

equals, getName, getSize, hashCode, isAvailable, isModifiedSince, openOutputStream, openStream, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SCHEME_PREFIX

public static final String SCHEME_PREFIX

The scheme-prefix for this type of DataResource.

See Also:

Constant Field Values

path

private final String path

See Also:

getUrl()

url

private final URL url

See Also:

getUrl()

Constructor Detail

ClasspathResource

public ClasspathResource(String absoluteClasspath)

The constructor.

Parameters:

absoluteClasspath - is the absolute path to the resource. E.g. "net/sf/mmm/util/resource/ClasspathResource.txt".

ClasspathResource

public ClasspathResource(Class<?> someClass,
                         String nameOrSuffix,
                         boolean append)

The constructor for a classpath-resource identified by someClass and the given nameOrSuffix.
E.g. the following code would get a resource named " ClasspathResource.xml" from the same package where this class is located:

 new ClasspathResource(ClasspathResource.class,
 ".xml", true)
 

This is the same as:

 new ClasspathResource(ClasspathResource.class,
 "ClasspathResource.xml", false)
 

This is the same as:

 new ClasspathResource("net/sf/mmm/util/resource/ClasspathResource.xml")
 

Parameters:

someClass - is the class identifying the path where the resource is located and the prefix of its filename.

nameOrSuffix - is the filename of the resource or a suffix (e.g. ".properties" or "-test.xml") for it depending on append.

append - - if true the nameOrSuffix is appended to the simple classname of someClass or false if the simple name is replaced by nameOrSuffix.

See Also:

ClasspathResource(Package, String)

ClasspathResource

public ClasspathResource(Package somePackage,
                         String filename)

The constructor. for a classpath-resource identified by somePackage and the given filename.
E.g. the following code would create a resource named "relection.properties" from the same package where this class is located:

 new ClasspathResource(ClasspathResource.class.getPackage(),
 "relection.properties")
 

This is the same as:

 new ClasspathResource(ClasspathResource.class, "relection.properties", false)
 

Parameters:

somePackage - is the package identifying the path where the resource is located.

filename - is the name of the resource.

See Also:

ClasspathResource(Class, String, boolean)

Method Detail

getSchemePrefix

public String getSchemePrefix()

This method gets the scheme-prefix of absolute URIs for this type of DataResource. The scheme-prefix has the following form: <scheme>:<suffix> where <suffix> is the empty string or something like //.

Specified by:

getSchemePrefix in class AbstractDataResource

Returns:

the scheme-prefix of this resource.

getAbsolutePath

private static String getAbsolutePath(Class<?> someClass,
                                      String nameOrSuffix,
                                      boolean append)

Parameters:

someClass - is the class identifying the path where the resource is located and the prefix of its filename.

nameOrSuffix - is the filename of the resource or a suffix (e.g. ".properties" or "-test.xml") for it depending on append.

append - - if true the nameOrSuffix is appended to the simple classname of someClass or false if the simple name is replaced by nameOrSuffix.

Returns:

the absolute path.

See Also:

ClasspathResource(Class, String, boolean)

isData

public boolean isData()

This method determines if this resource has potentially data available. Unlike DataResource.isAvailable() this method will not invoke expensive operations like connecting to remote URLs. If this method will return false, then DataResource.isAvailable() would also have returned false. However in case of true only DataResource.isAvailable() can guarantee if a resource really exists and contains data. E.g. if the resource points to a File then this method can check if it is a data-file. So in case it points to a directory or does not exist at all in the filesystem, this method will return false. Please also note that this may invoke expensive operations if the according directory path points to something like a network share. You should also be aware that the state of DataResource.isData() and DataResource.isAvailable() can change at any time so you never have a full guarantee if some data exists or NOT. However in most cases it is very improbable that this status changes when you read the resource immediately after the check.

Returns:

true if this resource points to potential data, false otherwise.

getPath

public String getPath()

This method gets the path of this resource. Please note that the path is including the name of the resource.
ATTENTION:
The result of this method may differ to the path used in the URL when this resource has been created.

Specified by:

getPath in interface DataResource

Overrides:

getPath in class AbstractDataResource

Returns:

the path that was used to identify this resource when creating.

getUrl

public URL getUrl()
           throws ResourceNotAvailableException

This method gets this resource as URL.

Returns:

the URL that represents this resource.

Throws:

ResourceNotAvailableException - if an URL can NOT be created because the represented resource does not exist.

getLastModificationDate

public Date getLastModificationDate()

This method gets the last modification date of the DataResource if available and supported.

Returns:

the last modification Date or null if not available or supported.

getUri

public String getUri()

This method gets a string identifying this DataResource. In most cases this will be the same as string-representation of the URL. However this method will not throw an exception.

Specified by:

getUri in interface DataResource

Overrides:

getUri in class AbstractDataResource

Returns:

the URI as string.

navigate

public DataResource navigate(String resourcePath)

This method retrieves a DataResource pointing to the given resourcePath based on this resource.
E.g. if this resource points to the file "/etc/init.d/rc" and resourcePath would be "../apt/sources.list" the resulting resource would point to "/etc/apt/sources.list".
ATTENTION:
As you can see by the example above this method always navigates relative to the parent folder of this resource. This will also be the case if this resource itself is a folder. Due to this generic API this is the only consistent way as there are implementations that can not easily know if they represent a folder or a file or maybe even both at the same time. However, please be aware of this and do not get confused as you might expect this to be a cd command if invoked on a folder what is not exactly not the case (instead it is a cd on the parent folder).

Parameters:

resourcePath - is the absolute or relative path pointing to a new resource. If it is a relative path, it is interpreted relative to the parent URI (directory) of this resource.

Returns:

is the resource pointing to the given path (relative to this resource).