Class next.util.Bundle

CLASS DESCRIPTION

Extends:
next.util.NextObject

A Bundle 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 Bundle object makes those resources available to the application. Bundle can find requested resources in the directory and can dynamically load executable code. 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. Bundles are also used to locate specific resources, to obtain localized strings, to load code dynamically, and to determine which classes are loaded.

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

For all types of bundles, the executable-code file of a bundle (of which there can be only one) is in the immediate bundle directory and takes the same name as the bundle, minus the extension. Bundles also encode (as a property list) the important attributes of the bundle, such as the main nib file name, executable name, document extensions, and so forth. You can access these attributes with Bundle's infoDictionary method, which returns the file's contents as an ImmutableHashtable.

You shouldn't attempt subclassing Bundle since during initialization the bundle might substitute another Bundle for self.

The Main Bundle

Every application has at least one bundle-its main bundle-which is the ".app" directory where its executable file is located. This file is loaded into memory when the application is launched. It includes at least the main() function and other code necessary to start up the application. You obtain an Bundle object corresponding to the main bundle with the static method mainBundle.

Framework Bundles

Frameworks are bundles that package dynamic shared libraries along with the nib files, images, and other resources that support the executable code and with the header files and documentation that describe the associated APIs. As long as your applications are dynamically linked with frameworks, you should have little need to do anything explicitly with those frameworks thereafter; in a running application, the framework code is automatically loaded, as needed. See Programming in the NEXTSTEP Development Environment for more information about frameworks.

Loadable Bundles and Dynamic Loading

An application can be organized into any number of other bundles in addition to the main bundle and the bundles of linked-in frameworks. Although these loadable bundles usually reside inside the application file package, they can be located anywhere in the file system. Each loadable-bundle directory-by convention, with a ".bundle" extension-is represented in the application by a separate Bundle object. Through this object the application can dynamically load the code and resources in the bundle when it needs them. For example, an application for managing PostScript printers may have a bundle full of PostScript code to be downloaded to printers.

The major advantage of bundles is application extensibility. A set of bundled classes often supports a small collection of objects that can be integrated into the larger object network already in place. (NEXTSTEP Preferences is one example of this.) The linkage is established through an instance of the principal class. This object might have methods to return other objects that the application can talk to, but typically all messages from the application to the subnetwork are funneled through the one instance.

Since each bundle can have only one executable file, that file should be kept free of localizable content. Anything that needs to be localized should be segregated into separate resource files and stored in localized-resource subdirectories.

To create a loadable bundle-a bundle with dynamically loadable code-without using Project Builder, use the ld(1) -bundle flag on the cc command line.

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, Hindu, and Swedish versions of the character strings that label menu commands.

Resource files specific to a particular language are grouped together in a subdirectory of the bundle directory. The subdirectory 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, Hindi.lproj, and Swedish.lproj subdirectories. Each ".lproj" subdirectory in a bundle has the same set of files; all versions of a resource file must have the same name. Thus, Hello.snd in French.lproj should be the French counterpart to the Swedish Hello.snd in Swedish.lproj, and so on. If a resource doesn't need to be localized at all, it's stored in the bundle directory itself, not in the ".lproj" subdirectories.

The user determines which set of localized resources will actually be used by the application. Bundle objects rely on the language preferences set by the user in the Preferences application. Preferences lets users order a list of available languages so thatthe most preferred language is first, the second most preferred language is second, and so on.

When a Bundle is asked for a resource file, it provides the path to the resource that best matches the user's language preferences. For details, see the descriptions of pathForResource and pathForResourceInDirectory.


CONSTRUCTORS

Bundle

public Bundle()

Returns a newly-allocated and initialized Bundle object.


METHODS

bundlePath

public java.lang.String bundlePath()

Returns the full pathname of the receiver's bundle directory.


bundleWithPath

public static next.util.Bundle bundleWithPath(java.lang.String path)

Returns a Bundle that corresponds to the specified directory path or nil if path does not identify an accessible bundle directory. This method allocates and initializes the returned object if it doesn't already exist.


infoDictionary

public next.util.ImmutableHashtable infoDictionary()

Returns a HashTable that contains information about the receiver. This information is extracted from the property list (Info.plist) associated with the bundle. The returned dictionary is empty if no Info.plist can be found. Common keys for accessing the values of the dictionary are NSExecutable, NSExtensions, NSIcon, NSMainNibFile, and NSPrincipalClass.


mainBundle

public static next.util.Bundle mainBundle()

Returns a Bundle that corresponds to the directory where the application executable is located or nil if this executable is not located in a accessible bundle directory. This method allocates and initializes the returned Bundle if it doesn't already exist.

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 ".app" extension.


pathForResource

public java.lang.String pathForResource(java.lang.String resourceName, java.lang.String extension)

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


pathForResourceInDirectory

public java.lang.String pathForResourceInDirectory(java.lang.String resourceName, java.lang.String extension, java.lang.String bundlePath)

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

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


resourcePath

public java.lang.String resourcePath()

Returns the full pathname of the receiving bundle's subdirectory containing resources.