PATH |
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()
.woa
" extension.
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()
true
if the bundle was loaded at application startup, otherwise returns false
.
name
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.
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.
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)
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). |
principalClass
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; }
properties
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.
resourcePath
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. |
resourcePathsForDirectories
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
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)