org.xith3d.resources
Class ResourceLocator

java.lang.Object
  extended by 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:
dummy -
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