Documentation Archive Developer
Search
PATH Documentation > WebObjects

Table of Contents

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:


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.


Table 0-2 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" }


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:

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.


Table 0-3 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" }


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.


Table 0-4 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" }


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()

Deprecated in the Java Foundation framework. Don't use this method. The only non-framework bundle that an application can access without deprecated API is the main bundle. Use mainBundle instead. Returns an array containing all the non-framework bundles available to the application.

allFrameworks

public static NSArray allFrameworks()

Deprecated in the Java Foundation framework. Don't use this method. Use frameworkBundles instead.

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



bundleForClass

public synchronized static NSBundle bundleForClass(Class aClass)

Returns the bundle containing the class aClass.

bundleForName

public synchronized static NSBundle bundleForName(String name)

Returns the bundle with the specified name. See name for more information about how the name relates to the bundle on the file system.

bundleWithPath

public static NSBundle bundleWithPath(String path)

Deprecated in the Java Foundation framework. Don't use this method. To access a bundle that was loaded when the application started, use bundleForName or bundleForClass.

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()

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

mainBundle

public static NSBundle mainBundle()

Returns 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.


Instance Methods



bundleClassNames

public NSArray bundleClassNames()

Returns an array containing the names of all the receiver's classes.

bundleClassPackageNames

public NSArray bundleClassPackageNames()

Returns an array containing the names of all the packages containing the receiver's classes.

bundlePath

public String bundlePath()

Deprecated in the Java Foundation framework. Don't use this method. You should not need to know the file system path to the bundle directory.

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



bytesForResourcePath

public byte[] bytesForResourcePath(String resourcePath)

Returns a byte array containing the data for the resource specified by resourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" (page 26) for more information about resource paths.

infoDictionary

public NSDictionary infoDictionary()

Deprecated in the Java Foundation framework. Don't use this method.

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)

Returns an input stream for the resource specified by resourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" (page 26) for more information about resource paths.

isFramework

public boolean isFramework()

Returns whether the receiver represents a framework or not.

load

public boolean load()

Deprecated in the Java Foundation framework. Don't use this method. Dynamic loading is no longer supported. Returns true if the bundle was loaded at application startup, otherwise returns false.

name

public String name()

Returns the name of the bundle. If the bundle is a Java WebObjects Application, this method returns the name of the directory containing the application without the ".woa" extension. If the bundle is a Java WebObjects Framework, this method returns the name of the directory containing the framework without the ".framework" extension.

pathForResource

public String pathForResource( String name, String extension)

Deprecated in the Java Foundation framework. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.

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)

Deprecated in the Java Foundation framework. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.

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:

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.


Note: These methods search for resources based on the resource organization on the file system, not the internal NSBundle resource organization as described in the NSBundle class description. Specifically, these methods do not support the "Nonlocalized.lproj" directory. Also, the methods do not "drill-down" into the subdirectories of the specified bundle path (except for the language.lproj subdirectories).



pathsForResources

public NSArray pathsForResources( String extension, String bundlePath)

Deprecated in the Java Foundation framework. Don't use this method. Use resourcePathsForResources instead. Returns an array containing file system path names for all bundle resources having the specified file name extension and residing in the directory bundlePath; returns an empty array if no matching resource files are found. This method provides a means for dynamically discovering bundle resources. The argument bundlePath must be a valid bundle directory or null. The extension argument can be an empty string or null; if you specify either of these for extension, all bundle resources are returned. Although there is no guaranteed search order, all of the following directories will be searched:

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


Note: This method searches for resources based on the resource organization on the file system, not the internal NSBundle resource organization as described in the NSBundle class description. Specifically, these methods do not support the "Nonlocalized.lproj" directory. Also, the methods do not "drill-down" into the subdirectories of the specified bundle path (except for the language.lproj subdirectories).



principalClass

public Class principalClass()

Returns the NSBundle's principal class. The principal class 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;
}



properties

public java.util.Properties properties()

Returns the receiver's properties. These properties are located in the Properties file in the Resources subdirectory of the directory corresponding to the receiver. See the NSBundle class for more information about the Properties file.

resourcePath

public String resourcePath()

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

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


Note: In the Java Foundation Framework, the term resource path refers to the full specification of the location of a resource in an NSBundle. In previous versions of the Foundation Framework, the term resource path referred to the file system path to the directory containing a bundle's resources.



resourcePathsForDirectories

public NSArray resourcePathsForDirectories(String extension, String subdirectory)

Returns an array containing the resource paths of all the directories with the specified extension beneath the specified subdirectory. If extension is null, the method includes directories regardless of extension. If subdirectory is null, the method returns directories beneath the top level directory (the one containing the language directories). For examples of how this method is used, see "Determining Available Resources" (page 26).

See Also: resourcePathsForResources, resourcePathsForLocalizedResources



resourcePathForLocalizedResourceNamed

public String resourcePathForLocalizedResourceNamed(String name, String subdirectory)

Returns the resource path for the localized resource with the specified name within the specified subdirectory. This method determines the resource path based on the current locale. See "Accessing NSBundle Resources" (page 29) for more information about how this method chooses the resource path it returns.

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)

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 "Determining Available Resources" (page 26) for more information about how this method chooses the resource paths it returns.

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)

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. For examples of how this method is used, see "Determining Available Resources" (page 26).

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()

Returns a string representation of the receiver including its 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.


Notifications


BundleDidLoadNotification

public static String BundleDidLoadNotification

LoadedClassesNotification

public static final String LoadedClassesNotification

Description forthcoming.

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


Table of Contents