NSBundle

Inherits from:

Object

Package:

com.webobjects.foundation

Class Description

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 Project Builder using a Java WebObjects Application or Java WebObjects Framework project.

An NSBundle is an object that corresponds to 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.

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 Project Builder, 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 Project Builder, 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 sans 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.

If you are unsure which bundles are loaded at startup, you can enable NSBundle debugging by setting the NSBundleDebugEnabled user default to true. NSBundle subsequently logs the paths to the bundles as it loads them.

Localized Resources

If an application is to be used in more than one part of the world, its resources may need to be customized, or "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:

Listing
0-1 Resource organization example
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

These resources appear on the file system as:

Listing
0-2 How the resources appear on the file
system
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 resource organization as it appears on the file system. For example, the resource path to the Background.jpeg resource in Listing 0-1 is Nonlocalized.lproj/Images/Background.jpeg.

resourcePathsForResources

The resourcePathsForResources method takes two arguments: a subdirectory and an extension. The method returns an NSArray containing resource path strings for the resources in the specified subdirectory that have the specified extension. If you specify null for the subdirectory, the method returns the resource paths for the resources starting from the top level. If you specify null for the extension, the method will not filter resources according to their extension. Table 0-2 shows examples of invoking resourcePathsForResources with various parameters for the bundle depicted in Listing 0-1.

resourcePathsForLocalizedResources

The resourcePathsForLocalizedResources method returns an NSArray of resource paths to resources that are appropriate for the current locale. 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.

The resourcePathsForLocalizedResourcesmethod also takes the extension and subdirectory arguments that allow you to filter the result array based on the extension or subdirectory. Table 0-3 shows examples of invoking resourcePathsForLocalizedResources with various parameters for the bundle depicted in Listing 0-1.

resourcePathsForDirectories

NSBundle also includes a method called resourcePathsForDirectories that returns the directories containing resources. It also takes the extension and subdirectory parameters. Table 0-4 shows examples of invoking resourcePathsForDirectories with various parameters for the bundle depicted in Listing 0-1.

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.

The resourcePathForLocalizedResourceNamed 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 for the method to search in. For example, if the current locale is English, and the resources are organized as shown in Listing 0-1, 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".

Method Types

Accessing resources

bytesForResourcePath

inputStreamForResourcePath

Finding bundles

frameworkBundles

bundleForClass

bundleForName

mainBundle

Getting resource paths

resourcePathsForDirectories

resourcePathForLocalizedResourceNamed

resourcePathsForLocalizedResources

resourcePathsForResources

Getting bundle class information

bundleClassPackageNames

bundleClassNames

Getting bundle attributes

isFramework

name

principalClass

properties

Methods inherited from Object

toString

Deprecated methods

allBundles

allFrameworks

bundlePath

bundleWithPath

infoDictionary

load

pathForResource

pathsForResources

resourcePath

Static Methods

allBundles

public synchronized static NSArray allBundles()

allFrameworks

public static NSArray allFrameworks()

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

bundleForClass

public synchronized static NSBundle bundleForClass(Class aClass)

bundleForName

public synchronized static NSBundle bundleForName(String name)

bundleWithPath

public static NSBundle bundleWithPath(String path)

Returns an NSBundle that corresponds to the specified directory path or returns null if path does not identify an accessible bundle directory.

If the bundle object for the specified directory doesn't already exists, this method creates the returned bundle.

frameworkBundles

public synchronized static NSArray frameworkBundles()

mainBundle

public static NSBundle mainBundle()

Instance Methods

bundleClassNames

public NSArray bundleClassNames()

bundleClassPackageNames

public NSArray bundleClassPackageNames()

bundlePath

public String bundlePath()

Returns the full file system path name of the receiver's bundle directory.

bytesForResourcePath

public byte[] bytesForResourcePath(String resourcePath)

infoDictionary

public NSDictionary infoDictionary()

Returns a dictionary that contains information about the receiver. This information is extracted from the property list associated with the bundle. The CustomInfo.plist file is a source file for the bundle's property list.

inputStreamForResourcePath

public java.io.InputStream inputStreamForResourcePath(String resourcePath)

isFramework

public boolean isFramework()

load

public boolean load()

name

public String name()

pathForResource

public String pathForResource( String name, String extension)

Returns the full file system path name for the resource identified by name with the specified file extension. If the extension argument is null or an empty string (""), the resource sought is identified by name, with any (or no) extension. The method first looks for a non-localized resource in the immediate bundle directory; if the resource is not there, it looks for the resource in the language-specific ".lproj" directory (the local language is determined by user defaults).

public String pathForResource( String name, String extension, String bundlePath)

Returns the full file system path name for the resource identified by name, with the specified file name extension, and residing in the directory bundlePath; returns null if no matching resource file exists in the bundle. The argument bundlePath must be a valid bundle directory or null. The argument extension can be an empty string or null; in either case the pathname returned is the first one encountered with name, regardless of the extension. The method searches in this order:

• <main bundle path>/Resources/bundlePath/name.extension
• <main bundle path>/Resources/bundlePath/<language.lproj>/name.extension
• <main bundle path>/bundlePath/name.extension
• <main bundle path>/bundlePath/<language.lproj>/name.extension

The order of language directories searched corresponds to the user's preferences. If bundlePath is null, the same search order as described above is followed, minus bundlePath.

pathsForResources

public NSArray pathsForResources( String extension, String bundlePath)

• <main bundle path>/Resources/bundlePath/name.extension
• <main bundle path>/Resources/bundlePath/<language.lproj>/name.extension
• <main bundle path>/bundlePath/name.extension
• <main bundle path>/bundlePath/<language.lproj>/name.extension

The language directories searched corresponds to the current locale. If bundlePath is null, the same search order as described above is followed, minus bundlePath.

principalClass

public Class principalClass()

{
    NSPrincipalClass = myPackage.myPrincipalClass;
}

properties

public java.util.Properties properties()

resourcePath

public String resourcePath()

Returns the full file system path name of the receiving bundle's subdirectory containing resources.

resourcePathsForDirectories

public NSArray resourcePathsForDirectories(String extension, String subdirectory)

See Also: resourcePathsForResources, resourcePathsForLocalizedResources

resourcePathForLocalizedResourceNamed

public String resourcePathForLocalizedResourceNamed(String name, String subdirectory)

If subdirectory is null, the method returns a resource path for a localized resource at the language directory level.

See Also: resourcePathsForLocalizedResources, resourcePathsForResources, resourcePathsForDirectories

resourcePathsForLocalizedResources

public NSArray resourcePathsForLocalizedResources(String extension, String subdirectory)

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

See Also: resourcePathsForResources, resourcePathsForDirectories

resourcePathsForResources

public NSArray resourcePathsForResources(String extension, String subdirectory)

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

See Also: resourcePathsForLocalizedResources, resourcePathsForDirectories

toString

public String toString()

Notifications

BundleDidLoadNotification

public static String BundleDidLoadNotification

LoadedClassesNotification

public static final String LoadedClassesNotification

© 2001 Apple Computer, Inc. (Last Published April 17, 2001)