| PATH |
- Inherits from:
- Object
- Package:
- com.webobjects.foundation
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:
NSBundle supports two types of bundles: application bundles and framework 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.
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.
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.
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.
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
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.
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.
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:
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.
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.
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".
- 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
public synchronized static NSArray allBundles()
public static NSArray allFrameworks()
Returns an array containing the bundles for all the frameworks included in the application.
public synchronized static NSBundle bundleForClass(Class aClass)
public synchronized static NSBundle bundleForName(String name)
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.
public synchronized static NSArray frameworkBundles()
public static NSBundle mainBundle()
.woa" extension.
public NSArray bundleClassNames()
public NSArray bundleClassPackageNames()
public String bundlePath()
Returns the full file system path name of the receiver's bundle directory.
public byte[] bytesForResourcePath(String resourcePath)
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.
public java.io.InputStream inputStreamForResourcePath(String resourcePath)
public boolean isFramework()
public boolean load()
true if the bundle was loaded at application startup, otherwise returns false.
public String name()
.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.
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.
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). |
public NSArray pathsForResources( String extension, String bundlePath)
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:
<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.
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). |
public Class principalClass()
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;
}
public java.util.Properties properties()
Properties file in the Resources subdirectory of the directory corresponding to the receiver. See the NSBundle class for more information about the Properties file.
public String resourcePath()
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. |
public NSArray resourcePathsForDirectories(String extension, String subdirectory)
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
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
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
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
public String toString()
public static String BundleDidLoadNotification
public static final String LoadedClassesNotification
© 2001 Apple Computer, Inc. (Last Published April 17, 2001)