com.webobjects.foundation
Class NSBundle

java.lang.Object
  com.webobjects.foundation.NSBundle

public class NSBundle

extends Object

An NSBundle represents a location in the file system that groups code and resources that can be used in a program. NSBundles locate program resources and assist in localization. You build a bundle in Xcode using a Java WebObjects Application or Java WebObjects Framework project.

NSBundles can be stored on disk in two ways.

The first way is a directory where related resources--including executable code--are stored. The directory, in essence, "bundles" a set of resources used by an application into convenient chunks, and the NSBundle object makes those resources available to the application. NSBundle can find requested resources in the directory. The term bundle refers both to the object and to the directory it represents.

The second way is a java JAR file (Java ARchive). Again, all of the classes and resources are encapsulated into the JAR file. In this case, the term bundle refers to the JAR file itself.

At this point, JAR files are the preferred storage mechanism for NSBundles. However using JAR files requires that java.net.URLs be used to reference resources inside bundles. Path APIs (which typically operate on Strings) cannot be used. All Path APIs in the base WebObjects frameworks should be deprecated.

Bundles are useful in a variety of contexts. Since bundles combine executable code with the resources used by that code, they facilitate installation and localization. NSBundles are also used to locate specific resources and to determine which classes are loaded.

Each resource in a bundle usually resides in its own file. Bundled resources include such things as:

• Images--GIF or JPEG images displayed on web pages
• Localized character strings

Types of Bundles

NSBundle supports two types of bundles: application bundles and framework bundles.

Application Bundles

An application bundle is a bundle that contains the resources needed to launch the application. Its extension is ".woa". To build an application bundle with Xcode, use the Java WebObjects Application project type.

Every application has a single application bundle called the "main bundle". You obtain an NSBundle object corresponding to the main bundle with the mainBundle static method. This is typically the running application itself.

Framework Bundles

A framework bundle is a bundle associated with a framework: a directory containing shared classes along with the resources that go with those classes, such as images and localized strings. A framework directory has a ".framework" extension. To build a framework bundle with Xcode, use the Java WebObjects Framework project type.

You can get an NSBundle object associated with a framework by invoking the static method bundleForName specifying, as the argument, the name of the framework without the ".framework" extension. Alternatively you can invoke the bundleForClass method specifying a class that's defined in the framework. To get all the framework bundles available to your application, you can invoke the frameworkBundles static method.

Bundle Availability

When an application starts up, it loads all of the bundles represented by class path components. If the class path contains multiple framework bundles with the same name, only the first one is loaded; the rest are ignored.

Localized Resources

If an application is to be used in more than one part of the world, its resources may need to be localized for language, country, or cultural region. An application may need, for example, to have separate Japanese, English, French, German, and Spanish versions of the images that label submit buttons.

Resources specific to a particular language are grouped together in a resource directory. This directory has the name of the language (in English) followed by a ".lproj" extension (for "language project"). The application mentioned above, for example, would have Japanese.lproj, English.lproj, French.lproj, German.lproj, and Spanish.lproj directories. The application also has a Nonlocalized.lproj directory, which contains resources shared by all locales.

It is good programming practice to ensure that if a resource appears in one language directory it also appears in all the others. Thus, Icon.gif in French.lproj should be the French counterpart to the Spanish Icon.gif in Spanish.lproj, and so on. However this discipline is not completely necessary. If German.lproj does not contain an Icon.gif resource, the Icon.gif resource in Nonlocalized.lproj will be used instead.

The server's locale determines which set of localized resources will actually be used by the application. NSBundle objects invoke the java.util.Locale.getDefault method to determine the locale and chooses the localized resources accordingly.

How Resources Appear on the File System

A bundle's resources are stored in a directory named Resources within the bundle directory on the file system. Within the Resources directory are all of the language directories except Nonlocalized.lproj. The non-localized resources in the Nonlocalized.lproj directory are mapped into the top level of the Resources directory on the file system.

For example, suppose the NSBundle resources are organized as shown below in Xcode:

 English.lproj
     Edit.wo
         Edit.html
         Edit.wod
         Edit.woo
 Nonlocalized.lproj
     Edit.wo
         Edit.html
         Edit.wod
         Edit.woo
     Images
         Icon.gif
         Background.jpeg
     Main.wo
         Main.html
         Main.wod
         Main.woo
 

Then, these resources will appear on the file system as:

 Resources
     Edit.wo
         Edit.html
         Edit.wod
         Edit.woo
     Images
         Icon.gif
         Background.jpeg
     Main.wo
         Main.html
         Main.wod
         Main.woo
     English.lproj
         Edit.wo
             Edit.html
             Edit.wod
             Edit.woo
 

Determining Available Resources

NSBundle provides two methods to determine the resources it contains: resourcePathsForResources and resourcePathsForLocalizedResources. These methods return resource paths, or paths specified according to NSBundle's resource organization, not the physical resource organization as it appears on the file system. For example, the resource path to the Background.jpeg resource in above example is Nonlocalized.lproj/Images/Background.jpeg.

Accessing NSBundle Resources

NSBundle provides two methods to access resources: bytesForResourcePath and inputStreamForResourcePath. Both methods require a single argument: a full resource path as returned by the resourcePathsForResources and resourcePathsForLocalizedResources methods. The bytesForResourcePath method returns a byte array containing data for the resource specified by the path. The inputStreamForResourcePath returns an java.io.InputStream for the resource specified by the path.

Sometimes you want to access a localized resource without specifying the full resource path. For example, if you might want to get the Icon.gif resource appropriate for the current locale. To do this, you invoke resourcePathForLocalizedResourceNamed to determine the full resource path for the localized resource and, in turn, invoke bytesForResourcePath or inputStreamForResourcePath with the full path.

See Also:

mainBundle(), bundleForName(String), bundleForClass(Class), frameworkBundles(), resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String), resourcePathsForDirectories(String, String), bytesForResourcePath(String), inputStreamForResourcePath(String), resourcePathForLocalizedResourceNamed(String, String)

Field Summary

static String	BundleDidLoadNotification Notification that is sent when bundle has been loaded.
static String	LoadedClassesNotification Notification that is sent when classes of this NSBundle have been loaded.

Constructor Summary

NSBundle()

Method Summary

static NSArray	allBundles() Deprecated. The only non-framework bundle that an application can access without using deprecated APIs is the main bundle. Use mainBundle instead.
static NSArray	allFrameworks() Deprecated. Use frameworkBundles instead
NSArray	bundleClassNames() Gets array containing the names of all the receiver's classes
NSArray	bundleClassPackageNames() Gets an NSArray of the names of all the packages containing the receiver's classes.
static NSBundle	bundleForClass(Class aClass) Gets the NSBundle that contains the class aClass.
static NSBundle	bundleForName(String aName) Gets the NSBundle with the specified name aName.
String	bundlePath() Deprecated. You should not need to know the file system path to the bundle directory.
URL	bundlePathURL() Returns the URL to the NSBundle.
static NSBundle	bundleWithPath(String aPath) Deprecated. To access a bundle that was loaded when the application started, use bundleForName or bundleForClass instead
byte[]	bytesForResourcePath(String aResourcePath) Gets the byte array containing the data for the resource specified by aResourcePath.
static NSArray	frameworkBundles() Gets an NSArray containing the bundles for all the frameworks included in the application.
NSDictionary	infoDictionary() Deprecated. Do not use this method.
InputStream	inputStreamForResourcePath(String aResourcePath) Gets an input stream containing the resource specified by aResourcePath.
boolean	isFramework() Determines if this NSBundle object is a framework.
boolean	isJar() Determines if this NSBundle object represents a JAR file.
boolean	load() Deprecated. Don't use this method since "Dynamic loading" is no longer supported. The default ClassLoader does not allow true dynamic class loading, it loads only those classes in the classpath at launch time.
static NSBundle	mainBundle() Gets the application's main bundle.
String	name() Gets the name of this NSBundle object.
String	pathForResource(String aName, String anExtension) Deprecated. Use resourcePathForLocalizedResourceNamed instead.
String	pathForResource(String aName, String anExtension, String aSubDirPath) Deprecated. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.
NSArray	pathsForResources(String anExtension, String aSubDirPath) Deprecated. Don't use this method. Use resourcePathsForResources instead.
URL	pathURLForResourcePath(String aResourcePath) Returns an URL to the resource specified by aResourcePath.
Class	principalClass() Gets the NSBundle's principal class, which is responsible for ensuring that all classes in the framework are properly initialized.
Properties	properties() Get the properties that are located in the Properties file in the Resources subdirectory of the directory corresponding to this NSBundle.
String	resourcePath() Deprecated. Don't use this method. Resources are now accessed using the bytesForResourcePath and inputStreamForResourcePath methods.
String	resourcePathForLocalizedResourceNamed(String aName, String aSubDirPath) Determines the resource path of the resource named aName based on the current locale.
NSArray	resourcePathsForDirectories(String anExtension, String aSubDirPath) Gets an array containing the resource paths of all the directories with the specified extension anExtension beneath the specified subdirectory aSubDirPath.
NSArray	resourcePathsForLocalizedResources(String anExtension, String aSubDirPath) Gets an array containing the resource paths for all of the receiver's resources that are appropriate for the current locale, have the specified file extension anExtension, and lie within the specified subdirectory aSubDirPath.
NSArray	resourcePathsForResources(String anExtension, String aSubDirPath) Gets an array containing the resource paths of all of the receiver's resources that have the specified file extension anExtension and lie within the specified subdirectory aSubDirPath.
String	toString() The string returned includes the receiver's class name (NSBundle or a subclass), its name, its path, the names of its packages (as returned by bundleClassPackageNames), and the number of classes it contains.

Methods inherited from class java.lang.Object

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

Field Detail

BundleDidLoadNotification

public static final String BundleDidLoadNotification

Notification that is sent when bundle has been loaded.

LoadedClassesNotification

public static final String LoadedClassesNotification

Notification that is sent when classes of this NSBundle have been loaded.

Constructor Detail

NSBundle

public NSBundle()

Method Detail

allBundles

public static NSArray allBundles()

Deprecated. The only non-framework bundle that an application can access without using deprecated APIs is the main bundle. Use mainBundle instead.

Returns:

an array containing all the non-framework bundles available to the application.

See Also:

mainBundle()

allFrameworks

public static NSArray allFrameworks()

Deprecated. Use frameworkBundles instead

Returns:

an array containing the bundles for all the frameworks included in the application.

See Also:

frameworkBundles()

bundleClassNames

public NSArray bundleClassNames()

Gets array containing the names of all the receiver's classes

Returns:

the found NSArray of class names

bundleClassPackageNames

public NSArray bundleClassPackageNames()

Gets an NSArray of the names of all the packages containing the receiver's classes.

Returns:

the found NSArray

bundleForClass

public static NSBundle bundleForClass(Class aClass)

Gets the NSBundle that contains the class aClass.

Parameters:

aClass - the class which belongs to the returned bundle

Returns:

the bundle containing the class aClass

bundleForName

public static NSBundle bundleForName(String aName)

Gets the NSBundle with the specified name aName. See name() for more information about how the name relates to the NSBundle's file system organization. This should only be used to look up frameworks; the main bundle should be resolved using NSBundle.mainBundle()

Parameters:

aName - the name of the NSBundle

Returns:

an NSBundle if found; null otherwise

See Also:

name()

bundlePath

public String bundlePath()

Deprecated. You should not need to know the file system path to the bundle directory.

Returns:

complete path of the receiver's bundle directory

bundlePathURL

public URL bundlePathURL()

Returns the URL to the NSBundle. Currently, this will always be of the form file:/path/to/bundle

Returns:

complete URL to the receiver

bundleWithPath

public static NSBundle bundleWithPath(String aPath)

Deprecated. To access a bundle that was loaded when the application started, use bundleForName or bundleForClass instead

Parameters:

aPath - the input path identifying an accessible bundle

Returns:

an NSBundle if found; null otherwise

See Also:

bundleForName(String), bundleForClass(Class)

bytesForResourcePath

public byte[] bytesForResourcePath(String aResourcePath)

Gets the byte array containing the data for the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:

aResourcePath - the path of the resource, according to the resources hierarchy

Returns:

the byte array

See Also:

resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

frameworkBundles

public static NSArray frameworkBundles()

Gets an NSArray containing the bundles for all the frameworks included in the application.

Returns:

the found NSArray of NSBundle

infoDictionary

public NSDictionary infoDictionary()

Deprecated. Do not use this method.

Returns:

a dictionary of information about the receiver

inputStreamForResourcePath

public InputStream inputStreamForResourcePath(String aResourcePath)

Gets an input stream containing the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:

aResourcePath - the path of the resource, according to the resources hierarchy

Returns:

the found input stream

See Also:

resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

isFramework

public boolean isFramework()

Determines if this NSBundle object is a framework.

Returns:

true if this NSBundle object is a framework else false

isJar

public boolean isJar()

Determines if this NSBundle object represents a JAR file.

Returns:

true if this NSBundle is a JAR file else false

Since:

5.2.2

load

public boolean load()

Deprecated. Don't use this method since "Dynamic loading" is no longer supported. The default ClassLoader does not allow true dynamic class loading, it loads only those classes in the classpath at launch time.

Returns:

true if bundle loaded at application startup, false otherwise

mainBundle

public static NSBundle mainBundle()

Gets the application's main bundle. In general, the main bundle corresponds to an application file package or application wrapper: a directory that bears the name of the application and is marked by a ".woa" extension.

Returns:

the main bundle of the application

name

public String name()

Gets the name of this NSBundle object. If the bundle is a WebObjects application, this method returns the name of the directory containing the application without the ".woa" extension. If the bundle is a WebObjects Framework, this method returns the name of the directory containing the framework without the ".framework" extension.

Returns:

the name of the current bundle

pathForResource

public String pathForResource(String aName,
                              String anExtension)

Deprecated. Use resourcePathForLocalizedResourceNamed instead.

Parameters:

aName -

anExtension -

Returns:

See Also:

resourcePathForLocalizedResourceNamed(String, String)

pathForResource

public String pathForResource(String aName,
                              String anExtension,
                              String aSubDirPath)

Deprecated. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.

Parameters:

aName -

anExtension -

aSubDirPath -

Returns:

See Also:

resourcePathForLocalizedResourceNamed(String, String)

pathURLForResourcePath

public URL pathURLForResourcePath(String aResourcePath)

Returns an URL to the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:

aResourcePath - the path of the resource, according to the resources hierarchy

Returns:

the URL to the resource

Since:

5.2.2

See Also:

resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

pathsForResources

public NSArray pathsForResources(String anExtension,
                                 String aSubDirPath)

Deprecated. Don't use this method. Use resourcePathsForResources instead.

Parameters:

anExtension -

aSubDirPath -

Returns:

See Also:

resourcePathsForResources(String, String)

principalClass

public Class principalClass()

Gets the NSBundle's principal class, which is responsible for ensuring that all classes in the framework are properly initialized. The NSBundle determines its principal class based on the bundle's property list. The property list represents a dictionary; the principle class is the value obtained using the key NSPrincipalClass. If the principal class is not specified in the property list, the method returns null. If you create a framework that needs to be initialized using a principal class, you must specify the class name in the CustomInfo.plist file, a source file for the bundle's property list. For example, if your principal class is myPackage.myPrincipalClass, your CustomInfo.plist file should look like:

 {
   NSPrincipalClass = myPackage.myPrincipalClass;
 }
 

Returns:

the NSBundle's principal class

properties

public Properties properties()

Get the properties that are located in the Properties file in the Resources subdirectory of the directory corresponding to this NSBundle.

Returns:

the properties found in the Properties file

resourcePath

public String resourcePath()

Deprecated. Don't use this method. Resources are now accessed using the bytesForResourcePath and inputStreamForResourcePath methods.

Returns:

See Also:

bytesForResourcePath(String), inputStreamForResourcePath(String)

resourcePathForLocalizedResourceNamed

public String resourcePathForLocalizedResourceNamed(String aName,
                                                    String aSubDirPath)

Determines the resource path of the resource named aName based on the current locale. This method first searches the current locale's language directory for the resource then the Nonlocalized.lproj directory. If it finds the resource, it returns the resource's path. Otherwise it returns null. You can specify a subdirectory aSubDirPath for the method to search in. For example, if the current locale is English, and the resources are organized as shown in the class description and you invoke resourcePathForLocalizedResourceNamed for the "Edit.html" resource in the "Edit.wo" subdirectory, the method returns "English.lproj/Edit.wo/Edit.html". If the current locale is German, the method returns "Nonlocalized.lproj/Edit.wo/Edit.html".

Parameters:

aName - the name of the resource

aSubDirPath - the subdirectory where it is searched; if it is null, the method returns a resource path for a localized resource at the language directory level.

Returns:

resource path for the localized resource with the specified name

See Also:

resourcePathsForLocalizedResources( String extension, String subdirectory), resourcePathsForResources(String extension, String subdirectory), resourcePathsForDirectories(String, String)

resourcePathsForDirectories

public NSArray resourcePathsForDirectories(String anExtension,
                                           String aSubDirPath)

Gets an array containing the resource paths of all the directories with the specified extension anExtension beneath the specified subdirectory aSubDirPath. If anExtension is null, the method includes directories regardless of extension. If aSubDirPath is null, the method returns directories beneath the top level directory (the one containing the language directories).

Examples of invoking resourcePathsForDirectories with various parameters for the bundle depicted in the class description.

Results of invoking resourcePathsForDirectories

extension	subdirectory	Result
null	null	{"English.lproj/Edit.wo", "English.lproj/Images", "Nonlocalized.lproj/Edit.wo", "Nonlocalized.lproj/Images", "Nonlocalized.lproj/Main.wo"}
"wo"	null	{"Nonlocalized.lproj/Main.wo", "Nonlocalized.lproj/Edit.wo", "English.lproj/Edit.wo"}
null	"English.lproj"	{"English.lproj/Edit.wo", "English.lproj/Images"}
"wo"	"English.lproj"	{"English.lproj/Edit.wo"}

Parameters:

anExtension - the extension of the resource

aSubDirPath - the directory where it is searched

Returns:

an array containing the resource paths of all the directories with the specified extension beneath the specified subdirectory.

See Also:

resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

resourcePathsForLocalizedResources

public NSArray resourcePathsForLocalizedResources(String anExtension,
                                                  String aSubDirPath)

Gets an array containing the resource paths for all of the receiver's resources that are appropriate for the current locale, have the specified file extension anExtension, and lie within the specified subdirectory aSubDirPath.

If a resource appears in more than one language directory, this method chooses whether to include it in the array based on the following criteria:

• If the resource appears in the language directory for the current locale, the method includes its path in the results array.
• If the resource appears in Nonlocalized.lproj but not in the current locale's language directory, the method includes its path in the results array.
• If the resource doesn't appear in Nonlocalized.lproj or the current locale's language directory the method does not include its path in the results array.

This method also takes the extension and subdirectory arguments that allow you to filter the result array based on the extension or subdirectory. Examples of invoking this method with various parameters for the bundle depicted in the class description.

Results of invoking resourcePathsForLocalizedResources

extension	subdirectory	Result
null	null	{ "English.lproj/Edit.wo/Edit.html", "English.lproj/Edit.wo/Edit.wod", "English.lproj/Edit.wo/Edit.woo", "Nonlocalized.lproj/Images/Icon.gif", "Nonlocalized.lproj/Images/Background.jpeg", "Nonlocalized.lproj/Main.wo/Main.html", "Nonlocalized.lproj/Main.wo/Main.wod", "Nonlocalized.lproj/Main.wo/Main.woo" }
"html"	null	{ "English.lproj/Edit.wo/Edit.html", "Nonlocalized.lproj/Main.wo/Main.html" }
null	"Edit.wo"	{ "English.lproj/Edit.wo/Edit.html", "English.lproj/Edit.wo/Edit.wod", "English.lproj/Edit.wo/Edit.woo" }
"html"	"Edit.wo"	{ "English.lproj/Edit.wo/Edit.html" }

Parameters:

anExtension - extension of the resource

aSubDirPath - the directory where it is searched

Returns:

an array containing the resource paths for all of the receiver's resources that are appropriate for the current locale, have the specified file extension, and lie within the specified subdirectory

See Also:

resourcePathsForResources(String, String), resourcePathsForDirectories(String, String)

resourcePathsForResources

public NSArray resourcePathsForResources(String anExtension,
                                         String aSubDirPath)

Gets an array containing the resource paths of all of the receiver's resources that have the specified file extension anExtension and lie within the specified subdirectory aSubDirPath.

If anExtension is null, the method includes resources regardless of extension. If aSubDirPath is null, the method returns resources beneath the top level directory (the one containing the language directories).

The following shows examples of invoking this method with various parameters for the bundle depicted in the class description.

Results from invoking resourcePathsForResources.

extension	subdirectory	Result
null	null	{ "English.lproj/Edit.wo/Edit.html", "English.lproj/Edit.wo/Edit.wod", "English.lproj/Edit.wo/Edit.woo", "English.lproj/Images/Icon.gif", "Nonlocalized.lproj/Edit.wo/Edit.html", "Nonlocalized.lproj/Edit.wo/Edit.wod", "Nonlocalized.lproj/Edit.wo/Edit.woo", Nonlocalized.lproj/Images/Icon.gif", "Nonlocalized.lproj/Images/Background.jpeg", "Nonlocalized.lproj/Main.wo/Main.html", "Nonlocalized.lproj/Main.wo/Main.wod", "Nonlocalized.lproj/Main.wo/Main.woo" }
"gif"	null	{ "English.lproj/Images/Icon.gif", "Nonlocalized.lproj/Images/Icon.gif" }
null	"English.lproj"	{ "English.lproj/Edit.wo/Edit.html", "English.lproj/Edit.wo/Edit.wod", "English.lproj/Edit.wo/Edit.woo", "English.lproj/Images/Icon.gif" }
"gif"	"English.lproj"	{ "English.lproj/Images/Icon.gif" }

Parameters:

anExtension - extension of the resource

aSubDirPath - the directory where it is searched

Returns:

an array containing the resource paths of all of the receiver's resources that have the specified file extension and lie within the specified subdirectory

See Also:

resourcePathsForDirectories(String, String), resourcePathsForLocalizedResources(String, String)

toString

public String toString()

The string returned includes the receiver's class name (NSBundle or a subclass), its name, its path, the names of its packages (as returned by bundleClassPackageNames), and the number of classes it contains.

Returns:

String giving details of this NSBundle object

See Also:

bundleClassPackageNames(), name()