com.webobjects.appserver
Class WOResourceManager

java.lang.Object
  |
  +--com.webobjects.appserver.WOResourceManager

public class WOResourceManager

extends Object

The WOResourceManager class manages all resources of an application. It is a singleton object, designed to be thread safe, assuming that only one WOResourceManager exists in any one address space.

Constructor Summary

protected

WOResourceManager() This is the default constructor for the WOResourceManager class.

Method Summary

byte[]	bytesForResourceNamed(String aResourceName, String aFrameworkName, NSArray aLanguagesList) Returns raw data for the specified resource.
String	contentTypeForResourceNamed(String aResourcePath) Finds the content type for a given resource name extension.
String	errorMessageUrlForResourceNamed(String aResourceName, String aFrameworkName) Error URL returned when a resource specified is not found.
void	flushDataCache() Removes all data from the dynamic data cache.
InputStream	inputStreamForResourceNamed(String aResourceName, String aFrameworkName, NSArray aLanguagesList) Returns a stream of data for the specified resource.
String	pathForResourceNamed(String aResourceName, String aFrameworkName, NSArray aLanguagesList) Deprecated. don't use this method. Use inputStreamForResourceNamed or bytesForResourceNamed instead.
void	removeDataForKey(String aKey, WOSession aSession) Removes the data stored in the dynamic data cache under the key aKey.
void	setData(NSData someData, String key, String type, WOSession aSession) Assigns someData to a key and caches it for later url retrieval.
String	stringForKey(String aKey, String aTableName, String aDefaultValue, String aFrameworkName, NSArray aLanguagesList) Searches aTableName using aKey to find a localized string.
String	toString()
String	urlForResourceNamed(String aResourceName, String aFrameworkName, NSArray aLanguagesList, WORequest aRequest) Returns the public url for the specified resource.

Methods inherited from class java.lang.Object

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

Constructor Detail

WOResourceManager

protected WOResourceManager()

This is the default constructor for the WOResourceManager class.

Method Detail

bytesForResourceNamed

public byte[] bytesForResourceNamed(String aResourceName,
                                    String aFrameworkName,
                                    NSArray aLanguagesList)

Returns raw data for the specified resource. When calling this method you must provide the name of the resource (including the filename extension) specified by aResourceName, the name of the framework in which the resource resides (or null if the resource resides within the application) specified by aFrameworkName, and an NSArray of String objects identifying the order in which the language-specific resources should be searched (supply null for this third argument specified by aLanguageList if the default order is sufficient). It is a good idea to start using this method instead of pathForResourceNamed as we will be changing the WebObjects resource packaging in the near future. This method calls inputStreamForResourceNamed with the same parameters.

Parameters:

aResourceName - name of the resource

aFrameworkName - name of the framework in which the resource resides

aLanguagesList - list of languages in specific order

Returns:

the contents of the specified resource as a byte array

contentTypeForResourceNamed

public String contentTypeForResourceNamed(String aResourcePath)

Finds the content type for a given resource name extension. The content type is determined based upon the filename extension; if the resource's filename supplied to this method has no extension or the extension isn't one of those listed in [/System, c:/Apple, /opt/Apple]/Library/Frameworks/JavaWebObjects.framework/Resources/MIME.plist this method returns "text/plain".

Parameters:

aResourcePath - file path of the resource, or just file name of the resource, as only the extension is required.

Returns:

HTTP content type for the named resource specified by aResourcePath

errorMessageUrlForResourceNamed

public String errorMessageUrlForResourceNamed(String aResourceName,
                                              String aFrameworkName)

Error URL returned when a resource specified is not found. If a resource name is not supplied (that is, if null is passed as the first parameter), the error message will contain "null" in place of the resource name. If a framework name is passed as the second parameter, the error message will have the following form: /ERROR/NOT_FOUND/framework=frameworkName/filename=resourceName. If null is passed as the second parameter, the error message will include the application name instead of a framework name and will have the following form: /ERROR/NOT_FOUND/app=applicationName/filename=resourceName.

Parameters:

aResourceName - the name of the resource

aFrameworkName - name of the framework in which the resource resides

Returns:

a String containing an error URL for the resource name specified by aResourceName and framework name specified by aFrameworkName

flushDataCache

public void flushDataCache()

Removes all data from the dynamic data cache. This method can be used to remove persistent dynamic data from the application-wide cache. Access to the WOResourceManager object is locked at the beginning of this method and unlocked at the end.

See Also:

removeDataForKey(java.lang.String, com.webobjects.appserver.WOSession), setData(com.webobjects.foundation.NSData, java.lang.String, java.lang.String, com.webobjects.appserver.WOSession)

inputStreamForResourceNamed

public InputStream inputStreamForResourceNamed(String aResourceName,
                                               String aFrameworkName,
                                               NSArray aLanguagesList)

Returns a stream of data for the specified resource. When calling this method you must provide the name of the resource (including the filename extension) specified by aResourceName, the name of the framework in which the resource resides (or null if the resource resides within the application) specified by aFrameworkName, and an NSArray of String objects identifying the order in which the language-specific resources should be searched (supply null for this third argument if the default order is sufficient) specified by aLanguageList. It is a good idea to start using this method instead of pathForResourceNamed as we will be changing the WebObjects resource packaging in the near future.

Parameters:

aResourceName - name of the resource

aFrameworkName - name of the framework in which the resource resides

aLanguagesList - list of languages in specific order

Returns:

a java.io.InputStream which can be used to read the contents of the specified resource

pathForResourceNamed

public String pathForResourceNamed(String aResourceName,
                                   String aFrameworkName,
                                   NSArray aLanguagesList)

Deprecated. don't use this method. Use inputStreamForResourceNamed or bytesForResourceNamed instead.

Returns the file path of the specified resource. Include the file's extension when specifying aResourceName. If the file is in the application, specify null for aFrameworkName.

This method always returns a path like /Local/Library/WebObjects/Applications/MyApp.woa/Contents/Resources/MyResource. It does not return the path relative to the HTTP server's document root unless the entire application is located in the document root.

Access to the WOResourceManager object is locked at the beginning of this method and unlocked at the end. Although WebObjects makes heavy use of this method internally, it is deprecated and inputStreamForResourceNamed or bytesForResourceNamed should be prefered when possible.

Be aware that this method is called very often internally by WebObjects. If you reimplement it, make sure it stays very fast!

Note that if you use Project Builder (rather than ProjectBuilderWO) and you add a folder of resources, they must be added as Folder References. This allows WOResourceManager to find them in rapid turnaround mode. Further, WOComponents (files in directories that have a .wo extension) are treated as opaque objects, so resources located in the .wo cannot be found by this method.

Parameters:

aResourceName - name of the resource

aFrameworkName - name of the framework in which the resource resides

aLanguagesList - list of languages in specific order

Returns:

the absolute path for the resource aResourceName

See Also:

urlForResourceNamed(java.lang.String, java.lang.String, com.webobjects.foundation.NSArray, com.webobjects.appserver.WORequest)

removeDataForKey

public void removeDataForKey(String aKey,
                             WOSession aSession)

Removes the data stored in the dynamic data cache under the key aKey. The session argument is currently ignored; in later implementations, specify null to have WOResourceManager use the application-wide cache.

WebObjects uses this method when a dynamic element requests an image or embedded object from a database and the key attribute is not set for that dynamic element. If the key attribute isn't set, the data retrieved from the database is stored in the cache using setData, sent to the dynamic element, and then removed from the cache using removeDataForKey. If the key attribute is set, removeDataForKey is not invoked.

You rarely needed to invoke this method. Use it only if you need to limit the amount of memory your application uses, if your application has data stored in the cache, and you know exactly which data is no longer needed.

Access to the WOResourceManager object is locked at the beginning of this method and unlocked at the end.

Parameters:

aKey - attribute in receivers request

aSession - the current WebObjects session

See Also:

flushDataCache(), setData(com.webobjects.foundation.NSData, java.lang.String, java.lang.String, com.webobjects.appserver.WOSession), removeDataForKey(java.lang.String, com.webobjects.appserver.WOSession)

setData

public void setData(NSData someData,
                    String key,
                    String type,
                    WOSession aSession)

Assigns someData to a key and caches it for later url retrieval. It adds the image or embedded object someData of MIME type type to the dynamic data cache for the session specified by aSession. The data is stored under the key key. The session argument is currently ignored; in later implementations, specify null to have WOResourceManager use the application-wide cache.

This method is invoked anytime a dynamic element requests an image or embedded object from a database. You rarely need to invoke it.

By default when a dynamic element requests an image from the database, or builds a graph on the fly, it tells the resource manager to store its data in a cache, using either a developer-specified key, or a random key. In return the dynamic element inserts a special url in the HTML so that the browser, on callback, can retrieve the data out of the resource manager cache and display it. If the key was specified by the component, the data stays in the cache as long as the cache is not flushed. If the key was randomly generated by the resource manager, the data is removed from the cache (using removeDataForKey), as soon as the browser retrieves it.

Access to the WOResourceManager object is locked at the beginning of this method and unlocked at the end.

Parameters:

someData - array of data

key - attribute in receivers request

type - type of the data

aSession - the current WebObjects session

See Also:

flushDataCache(), removeDataForKey(java.lang.String, com.webobjects.appserver.WOSession)

stringForKey

public String stringForKey(String aKey,
                           String aTableName,
                           String aDefaultValue,
                           String aFrameworkName,
                           NSArray aLanguagesList)

Searches aTableName using aKey to find a localized string. If no string value for the key is found in the table, aDefaultValue (optional) is returned. The method first searches the aTableName file, if it exists, in each of the localized (.lproj) subdirectories of the application wrapper; searching proceeds in the order specified by the array aLanguagesList. If no string value matching the key is found, the search then continues to the aTableName file (if it exists) directly under the Resources directory (inside the directory with the .woa extension).

Parameters:

aKey - attribute in the receiver's request

aTableName - the string table

aDefaultValue - returned when no value is found

aFrameworkName - name of the framework in which the resource resides

aLanguagesList - list of languages in specific order

Returns:

a localized string from the string table aTableName

toString

public String toString()

Overrides:

toString in class Object

Returns:

a String representation of the receiver

urlForResourceNamed

public String urlForResourceNamed(String aResourceName,
                                  String aFrameworkName,
                                  NSArray aLanguagesList,
                                  WORequest aRequest)

Returns the public url for the specified resource. The URL returned is of the following form: /WebObjects/MyApp.woa/Contents/WebServerResources/English.lproj/aResourceName.

Include the file's extension when specifying aResourceName. If the file is in the application, specify null for the framework argument.

This method locates webserver resources under the application or framework. The URL returned is computed by concatenating the application's base URL (returned by WOApplication's baseURL method and settable using the WOApplicationBaseURL property) and the relative path of the resource. This method does not check to see if the file is actually under the document root. For example, if the application is installed in /Local/Library/WebObjects/Applications, and the method finds aResourceName in the /Local/Library/WebObjects/Applications/MyApp.woa/Contents/WebServerResources directory, it returns /WebObjects/MyApp.woa/Contents/WebServerResources/aResourceName even though the WebServerResources directory may not yet be under the document root.

Access to the WOResourceManager object is locked at the beginning of this method and unlocked at the end.

Be aware that this method is called very often internally by WebObjects. If you reimplement it, make sure it stays very fast!

Parameters:

aResourceName - name of the resource

aFrameworkName - name of the framework in which the resource resides

aLanguagesList - list of languages in specific order

aRequest - request to resource handler to give the URL

Returns:

the URL associated with a resource named aResourceName

See Also:

pathForResourceNamed(java.lang.String, java.lang.String, com.webobjects.foundation.NSArray)