org.xith3d.resources
Class ResourceLocator

java.lang.Object
  org.xith3d.resources.ResourceLocator

public class ResourceLocator
extends java.lang.Object

The ResourceLocator serves as an abstraction layer to locate resources from a base folder or base URL.
Use the create(String) method to create an instance and the getResource(String) or getResourceAsStream(String) method to get child resources.
You can also create sub-ResourceLocators to handle sub-locations more easily.
If you want to use a specific instance as a singleton, you the setSingletonInstance(ResourceLocator) or useAsSingletonInstance() method. Then you can also use the ResLoc class to have shorter commands in your coding.

See Also:

ResLoc

Constructor Summary

protected	ResourceLocator(java.io.File baseFolder) Creates a new ResourceLocator instance.
protected	ResourceLocator(java.lang.Object dummy, java.lang.String baseResource) Creates a new ResourceLocator instance.
protected	ResourceLocator(java.lang.String foldername) Creates a new ResourceLocator instance.
	ResourceLocator(java.net.URL baseURL) Creates a new ResourceLocator instance with the given base-URL.

Method Summary

static ResourceLocator	create(java.lang.String baseResource) Creates a new ResourceLocator instance.
org.jagatoo.loaders.textures.locators.TextureStreamLocator	createAndAddTSL() Creates a TextureStreamLocator and adds it to the TextureLoader.
org.jagatoo.loaders.textures.locators.TextureStreamLocator	createAndAddTSL(java.lang.String resourceName) Creates a TextureStreamLocator and adds it to the TextureLoader.
java.util.List<java.net.URL>	findAllResources(java.lang.String extension, boolean recursively, boolean foldersToo) Searches for all child resources in this ResourceLoator.
java.net.URL	getBaseURL()
static ResourceLocator	getInstance() If you want to use one ResourceLocator as a singleton, use this.
java.net.URL	getResource(java.lang.String name) Creates a resource as a URL from this ResourceLocator.
java.io.InputStream	getResourceAsStream(java.lang.String name) Creates a resource as a URL from this ResourceLocator.
ResourceLocator	getSubLocator(java.lang.String subResource) Creates a new ResourceLocator instance with the sub-URL as its baseURL.
org.jagatoo.loaders.textures.locators.TextureStreamLocatorURL	getTSL() Creates a TextureStreamLocator to be added to the TextureLoader.
org.jagatoo.loaders.textures.locators.TextureStreamLocatorURL	getTSL(java.lang.String resourceName) Creates a TextureStreamLocator to be added to the TextureLoader.
protected void	setBaseURL(java.io.File baseFolder) Sets the baseURL.
protected void	setBaseURL(java.lang.String foldername) Sets the baseURL.
protected void	setBaseURL(java.net.URL baseURL) Sets the base-URL of this ResourceLocator.
static void	setSingletonInstance(ResourceLocator resLoc) If you want to use one ResourceLocator as a singleton, first invoke this and then use the getInstance() method to access the instance everywhere.
void	useAsSingletonInstance() If you want to use one ResourceLocator as a singleton, first invoke this and then use the getInstance() method to access the instance everywhere.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ResourceLocator

public ResourceLocator(java.net.URL baseURL)

Creates a new ResourceLocator instance with the given base-URL.
No check for availability is done on the baseURL.

Parameters:

baseURL -

ResourceLocator

protected ResourceLocator(java.io.File baseFolder)
                   throws java.io.FileNotFoundException,
                          java.lang.IllegalArgumentException

Creates a new ResourceLocator instance. The given baseFolder is converted to a URL and is taken as the base-URL of the new instance.

Parameters:

baseFolder -

Throws:

java.io.FileNotFoundException - if the folder does not exist

java.lang.IllegalArgumentException - if the baseFolder is not a directory

ResourceLocator

protected ResourceLocator(java.lang.String foldername)
                   throws java.io.FileNotFoundException,
                          java.lang.IllegalArgumentException

Creates a new ResourceLocator instance. The given baseFolder is converted to a URL and is taken as the base-URL of the new instance.

Parameters:

foldername -

Throws:

java.io.FileNotFoundException - if the folder does not exist

java.lang.IllegalArgumentException - if the baseFolder is not a directory

ResourceLocator

protected ResourceLocator(java.lang.Object dummy,
                          java.lang.String baseResource)

Creates a new ResourceLocator instance. The given baseResource is first converted to a slash-only form. If it doesn't end with '/', one slash is appended. If a resource with this name can be retrieved from the ClassLoader, it is taken as the baseURL for the new instance. If the resource couldn't be retrieved, a file with that name is checked for existance and for being a directory. If this is a hit, it is converted to a URL and taken as the baseURL for the new instance. Otherwise an IllegalArgumentException is thrown with more info.

Parameters:

baseResource -

Throws:

java.lang.IllegalArgumentException - if something is wrong with the given baseResource

Method Detail

setSingletonInstance

public static void setSingletonInstance(ResourceLocator resLoc)

If you want to use one ResourceLocator as a singleton, first invoke this and then use the getInstance() method to access the instance everywhere.

Parameters:

resLoc - the ResourceLocator instance to use as the singleton instance

See Also:

useAsSingletonInstance(), getInstance(), ResLoc

useAsSingletonInstance

public void useAsSingletonInstance()

If you want to use one ResourceLocator as a singleton, first invoke this and then use the getInstance() method to access the instance everywhere.

See Also:

setSingletonInstance(ResourceLocator), getInstance(), ResLoc

getInstance

public static ResourceLocator getInstance()

If you want to use one ResourceLocator as a singleton, use this. But remember to first (once) invoke the setSingletonInstance() method.

Returns:

the singleton instance (if already set)

See Also:

setSingletonInstance(ResourceLocator), ResLoc

setBaseURL

protected void setBaseURL(java.net.URL baseURL)

Sets the base-URL of this ResourceLocator.

setBaseURL

protected void setBaseURL(java.io.File baseFolder)
                   throws java.io.FileNotFoundException,
                          java.lang.IllegalArgumentException

Sets the baseURL. The given baseFolder is converted to a URL and is taken as the base-URL of the new instance.

Parameters:

baseFolder -

Throws:

java.io.FileNotFoundException - if the folder does not exist

java.lang.IllegalArgumentException - if the baseFolder is not a directory

setBaseURL

protected void setBaseURL(java.lang.String foldername)
                   throws java.io.FileNotFoundException,
                          java.lang.IllegalArgumentException

Sets the baseURL. The given baseFolder is converted to a URL and is taken as the base-URL of the new instance.

Parameters:

foldername -

Throws:

java.io.FileNotFoundException - if the folder does not exist

java.lang.IllegalArgumentException - if the baseFolder is not a directory

getBaseURL

public java.net.URL getBaseURL()

Returns:

the base-URL of this ResourceLocator

getSubLocator

public ResourceLocator getSubLocator(java.lang.String subResource)
                              throws java.net.MalformedURLException

Creates a new ResourceLocator instance with the sub-URL as its baseURL.

Parameters:

subResource - the relative resource to complete with this instance's baseURL to the new instance's baseURL

Returns:

the new sub-ResourceLocator

Throws:

java.net.MalformedURLException - if something was wrong with the resource

getResource

public java.net.URL getResource(java.lang.String name)
                         throws java.net.MalformedURLException

Creates a resource as a URL from this ResourceLocator. The given resource-name must be relative to this instance's baseURL.

Parameters:

name - the relative resource to complete with this instance's baseURL to an absolute one

Returns:

the resource

Throws:

java.net.MalformedURLException - if something was wrong with the resource

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String name)
                                        throws java.net.MalformedURLException,
                                               java.io.IOException

Creates a resource as a URL from this ResourceLocator. The given resource-name must be relative to this instance's baseURL.

Parameters:

name - the relative resource to complete with this instance's baseURL to an absolute one

Returns:

an InputStream from the resource

Throws:

java.net.MalformedURLException - if something was wrong with the resource

java.io.IOException - when the InputStream could not be created

findAllResources

public java.util.List<java.net.URL> findAllResources(java.lang.String extension,
                                                     boolean recursively,
                                                     boolean foldersToo)

Searches for all child resources in this ResourceLoator.

Parameters:

extension -

recursively -

foldersToo -

Returns:

a List of all found resources

getTSL

public org.jagatoo.loaders.textures.locators.TextureStreamLocatorURL getTSL(java.lang.String resourceName)
                                                                     throws java.net.MalformedURLException

Creates a TextureStreamLocator to be added to the TextureLoader.

Parameters:

resourceName - the relative resource to complete with this instance's baseURL to an absolute one It is taken as the constructor's argument for the TextureStreamLocatorURL.

Returns:

the created TextureStreamLocatorURL to be added to the TextureLoader

Throws:

java.net.MalformedURLException - if something was wrong with the resource

getTSL

public org.jagatoo.loaders.textures.locators.TextureStreamLocatorURL getTSL()

Creates a TextureStreamLocator to be added to the TextureLoader. The result of getBaseURL() is taken as the constructor's argument for the TextureStreamLocatorURL.

Returns:

the created TextureStreamLocatorURL to be added to the TextureLoader

createAndAddTSL

public org.jagatoo.loaders.textures.locators.TextureStreamLocator createAndAddTSL(java.lang.String resourceName)
                                                                           throws java.net.MalformedURLException

Creates a TextureStreamLocator and adds it to the TextureLoader.

Parameters:

resourceName - the relative resource to complete with this instance's baseURL to an absolute one It is taken as the constructor's argument for the TextureStreamLocatorURL.

Throws:

java.net.MalformedURLException - if something was wrong with the resource

createAndAddTSL

public org.jagatoo.loaders.textures.locators.TextureStreamLocator createAndAddTSL()

Creates a TextureStreamLocator and adds it to the TextureLoader. The result of getBaseURL() is taken as the constructor's argument for the TextureStreamLocatorURL.

create

public static ResourceLocator create(java.lang.String baseResource)

Creates a new ResourceLocator instance. The given baseResource is first converted to a slash-only form. If it doesn't end with '/', one slash is appended. If a resource with this name can be retrieved from the ClassLoader, it is taken as the baseURL for the new instance. If the resource couldn't be retrieved, a file with that name is checked for existance and for being a directory. If this is a hit, it is converted to a URL and taken as the baseURL for the new instance. Otherwise an IllegalArgumentException is thrown with more info.

Parameters:

baseResource -

Returns:

the new created ResourceLocator instance

Throws:

java.lang.IllegalArgumentException - if something is wrong with the given baseResource