Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
WebObjects 5.2.2
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.webobjects.foundation
Class NSBundle

java.lang.Object
  |
  +--com.webobjects.foundation.NSBundle
public class NSBundle
extends Object

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.

NSBundles can be stored on disk in two ways.

The first way is 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.

The second way is a java JAR file (Java ARchive). Again, all of the classes and resources are encapsulated into the JAR file. In this case, the term bundle refers to the JAR file itself.

At this point, JAR files are the preferred storage mechanism for NSBundles. However using JAR files requires that java.net.URLs be used to reference resources inside bundles. Path APIs (which typically operate on Strings) cannot be used. All Path APIs in the base WebObjects frameworks should be deprecated.

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

Localized Resources

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

 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
Then, these resources will appear on the file system as: 
 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 physical resource organization as it appears on the file system. For example, the resource path to the Background.jpeg resource in above example is Nonlocalized.lproj/Images/Background.jpeg.

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.

See Also:
mainBundle(), bundleForName(String), bundleForClass(Class), frameworkBundles(), resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String), resourcePathsForDirectories(String, String), bytesForResourcePath(String), inputStreamForResourcePath(String), resourcePathForLocalizedResourceNamed(String, String)

Field Summary
static String BundleDidLoadNotification
          Notification that is sent when bundle has been loaded.
static String LoadedClassesNotification
          Notification that is sent when classes of this NSBundle have been loaded.
 
Constructor Summary
NSBundle()
           
 
Method Summary
static NSArray allBundles()
          Deprecated. The only non-framework bundle that an application can access without using deprecated APIs is the main bundle. Use mainBundle instead.
static NSArray allFrameworks()
          Deprecated. Use frameworkBundles instead
 NSArray bundleClassNames()
          Gets array containing the names of all the receiver's classes
 NSArray bundleClassPackageNames()
          Gets an NSArray of the names of all the packages containing the receiver's classes.
static NSBundle bundleForClass(Class aClass)
          Gets the NSBundle that contains the class aClass.
static NSBundle bundleForName(String aName)
          Gets the NSBundle with the specified name aName.
 String bundlePath()
          Deprecated. You should not need to know the file system path to the bundle directory.
static NSBundle bundleWithPath(String aPath)
          Deprecated. To access a bundle that was loaded when the application started, use bundleForName or bundleForClass instead
 byte[] bytesForResourcePath(String aResourcePath)
          Gets the byte array containing the data for the resource specified by aResourcePath.
static NSArray frameworkBundles()
          Gets an NSArray containing the bundles for all the frameworks included in the application.
 NSDictionary infoDictionary()
          Deprecated. Do not use this method.
 InputStream inputStreamForResourcePath(String aResourcePath)
          Gets an input stream containing the resource specified by aResourcePath.
 boolean isFramework()
          Determines if this NSBundle object is a framework.
 boolean isJar()
          Determines if this NSBundle object represents a JAR file.
 boolean load()
          Deprecated. Don't use this method since "Dynamic loading" is no longer supported. The default ClassLoader does not allow true dynamic class loading, it loads only those classes in the classpath at launch time.
static NSBundle mainBundle()
          Gets the application's main bundle.
 String name()
          Gets the name of this NSBundle object.
 String pathForResource(String aName, String anExtension)
          Deprecated. Use resourcePathForLocalizedResourceNamed instead.
 String pathForResource(String aName, String anExtension, String aSubDirPath)
          Deprecated. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.
 NSArray pathsForResources(String anExtension, String aSubDirPath)
          Deprecated. Don't use this method. Use resourcePathsForResources instead.
 URL pathURLForResourcePath(String aResourcePath)
          Returns an URL to the resource specified by aResourcePath.
 Class principalClass()
          Gets the NSBundle's principal class, which is responsible for ensuring that all classes in the framework are properly initialized.
 Properties properties()
          Get the properties that are located in the Properties file in the Resources subdirectory of the directory corresponding to this NSBundle.
 String resourcePath()
          Deprecated. Don't use this method. Resources are now accessed using the bytesForResourcePath and inputStreamForResourcePath methods.
 String resourcePathForLocalizedResourceNamed(String aName, String aSubDirPath)
          Determines the resource path of the resource named aName based on the current locale.
 NSArray resourcePathsForDirectories(String anExtension, String aSubDirPath)
          Gets an array containing the resource paths of all the directories with the specified extension anExtension beneath the specified subdirectory aSubDirPath.
 NSArray resourcePathsForLocalizedResources(String anExtension, String aSubDirPath)
          Gets 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 anExtension, and lie within the specified subdirectory aSubDirPath.
 NSArray resourcePathsForResources(String anExtension, String aSubDirPath)
          Gets an array containing the resource paths of all of the receiver's resources that have the specified file extension anExtension and lie within the specified subdirectory aSubDirPath.
 String toString()
          The string returned includes the receiver's 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BundleDidLoadNotification

public static final String BundleDidLoadNotification
Notification that is sent when bundle has been loaded.

LoadedClassesNotification

public static final String LoadedClassesNotification
Notification that is sent when classes of this NSBundle have been loaded.

Constructor Detail

NSBundle

public NSBundle()
Method Detail

allBundles

public static NSArray allBundles()
Deprecated. The only non-framework bundle that an application can access without using deprecated APIs is the main bundle. Use mainBundle instead.

Returns:
an array containing all the non-framework bundles available to the application.
See Also:
mainBundle()

allFrameworks

public static NSArray allFrameworks()
Deprecated. Use frameworkBundles instead

Returns:
an array containing the bundles for all the frameworks included in the application.
See Also:
frameworkBundles()

bundleClassNames

public NSArray bundleClassNames()
Gets array containing the names of all the receiver's classes

Returns:
the found NSArray of class names

bundleClassPackageNames

public NSArray bundleClassPackageNames()
Gets an NSArray of the names of all the packages containing the receiver's classes.

Returns:
the found NSArray

bundleForClass

public static NSBundle bundleForClass(Class aClass)
Gets the NSBundle that contains the class aClass.

Parameters:
aClass - the class which belongs to the returned bundle
Returns:
the bundle containing the class aClass

bundleForName

public static NSBundle bundleForName(String aName)
Gets the NSBundle with the specified name aName. See name() for more information about how the name relates to the NSBundle's file system organization. This should only be used to look up frameworks; the main bundle should be resolved using NSBundle.mainBundle()

Parameters:
aName - the name of the NSBundle
Returns:
an NSBundle if found; null otherwise
See Also:
name()

bundlePath

public String bundlePath()
Deprecated. You should not need to know the file system path to the bundle directory.

Returns:
complete path of the receiver's bundle directory

bundleWithPath

public static NSBundle bundleWithPath(String aPath)
Deprecated. To access a bundle that was loaded when the application started, use bundleForName or bundleForClass instead

Parameters:
aPath - the input path identifying an accessible bundle
Returns:
an NSBundle if found; null otherwise
See Also:
bundleForName(String), bundleForClass(Class)

bytesForResourcePath

public byte[] bytesForResourcePath(String aResourcePath)
Gets the byte array containing the data for the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:
aResourcePath - the path of the resource, according to the resources hierarchy
Returns:
the byte array
See Also:
resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

frameworkBundles

public static NSArray frameworkBundles()
Gets an NSArray containing the bundles for all the frameworks included in the application.

Returns:
the found NSArray of NSBundle

infoDictionary

public NSDictionary infoDictionary()
Deprecated. Do not use this method.

Returns:
a dictionary of information about the receiver

inputStreamForResourcePath

public InputStream inputStreamForResourcePath(String aResourcePath)
Gets an input stream containing the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:
aResourcePath - the path of the resource, according to the resources hierarchy
Returns:
the found input stream
See Also:
resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

isFramework

public boolean isFramework()
Determines if this NSBundle object is a framework.

Returns:
true if this NSBundle object is a framework else false

isJar

public boolean isJar()
Determines if this NSBundle object represents a JAR file.

Returns:
true if this NSBundle is a JAR file else false

load

public boolean load()
Deprecated. Don't use this method since "Dynamic loading" is no longer supported. The default ClassLoader does not allow true dynamic class loading, it loads only those classes in the classpath at launch time.

Returns:
true if bundle loaded at application startup, false otherwise

mainBundle

public static NSBundle mainBundle()
Gets 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.

Returns:
the main bundle of the application

name

public String name()
Gets the name of this NSBundle object. If the bundle is a WebObjects application, this method returns the name of the directory containing the application without the ".woa" extension. If the bundle is a WebObjects Framework, this method returns the name of the directory containing the framework without the ".framework" extension.

Returns:
the name of the current bundle

pathForResource

public String pathForResource(String aName,
                              String anExtension)
Deprecated. Use resourcePathForLocalizedResourceNamed instead.

Parameters:
aName -
anExtension -
Returns:
See Also:
resourcePathForLocalizedResourceNamed(String, String)

pathForResource

public String pathForResource(String aName,
                              String anExtension,
                              String aSubDirPath)
Deprecated. Don't use this method. Use resourcePathForLocalizedResourceNamed instead.

Parameters:
aName -
anExtension -
aSubDirPath -
Returns:
See Also:
resourcePathForLocalizedResourceNamed(String, String)

pathURLForResourcePath

public URL pathURLForResourcePath(String aResourcePath)
Returns an URL to the resource specified by aResourcePath. The resource path must be specified relative to the top level of the resources hierarchy, that is, the directory containing the language subdirectories. It is usually returned from resourcePathsForResources or resourcePathsForLocalizedResources.

Note that the resource path for a resource is not the same as its file system path. See "Determining Available Resources" in the class description for more information about resource paths.

Parameters:
aResourcePath - the path of the resource, according to the resources hierarchy
Returns:
the URL to the resource
See Also:
resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

pathsForResources

public NSArray pathsForResources(String anExtension,
                                 String aSubDirPath)
Deprecated. Don't use this method. Use resourcePathsForResources instead.

Parameters:
anExtension -
aSubDirPath -
Returns:
See Also:
resourcePathsForResources(String, String)

principalClass

public Class principalClass()
Gets the NSBundle's principal class, which 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;
 }

Returns:
the NSBundle's principal class

properties

public Properties properties()
Get the properties that are located in the Properties file in the Resources subdirectory of the directory corresponding to this NSBundle.

Returns:
the properties found in the Properties file

resourcePath

public String resourcePath()
Deprecated. Don't use this method. Resources are now accessed using the bytesForResourcePath and inputStreamForResourcePath methods.

Returns:
See Also:
bytesForResourcePath(String), inputStreamForResourcePath(String)

resourcePathForLocalizedResourceNamed

public String resourcePathForLocalizedResourceNamed(String aName,
                                                    String aSubDirPath)
Determines the resource path of the resource named aName based on the current locale. This 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 aSubDirPath for the method to search in. For example, if the current locale is English, and the resources are organized as shown in the class description 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".

Parameters:
aName - the name of the resource
aSubDirPath - the subdirectory where it is searched; if it is null, the method returns a resource path for a localized resource at the language directory level.
Returns:
resource path for the localized resource with the specified name
See Also:
resourcePathsForLocalizedResources( String extension, String subdirectory), resourcePathsForResources(String extension, String subdirectory), resourcePathsForDirectories(String, String)

resourcePathsForDirectories

public NSArray resourcePathsForDirectories(String anExtension,
                                           String aSubDirPath)
Gets an array containing the resource paths of all the directories with the specified extension anExtension beneath the specified subdirectory aSubDirPath. If anExtension is null, the method includes directories regardless of extension. If aSubDirPath is null, the method returns directories beneath the top level directory (the one containing the language directories).

Examples of invoking resourcePathsForDirectories with various parameters for the bundle depicted in the class description.

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"}

Parameters:
anExtension - the extension of the resource
aSubDirPath - the directory where it is searched
Returns:
an array containing the resource paths of all the directories with the specified extension beneath the specified subdirectory.
See Also:
resourcePathsForResources(String, String), resourcePathsForLocalizedResources(String, String)

resourcePathsForLocalizedResources

public NSArray resourcePathsForLocalizedResources(String anExtension,
                                                  String aSubDirPath)
Gets 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 anExtension, and lie within the specified subdirectory aSubDirPath.

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:

This method also takes the extension and subdirectory arguments that allow you to filter the result array based on the extension or subdirectory. Examples of invoking this method with various parameters for the bundle depicted in the class description.

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" }

Parameters:
anExtension - extension of the resource
aSubDirPath - the directory where it is searched
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 Also:
resourcePathsForResources(String, String), resourcePathsForDirectories(String, String)

resourcePathsForResources

public NSArray resourcePathsForResources(String anExtension,
                                         String aSubDirPath)
Gets an array containing the resource paths of all of the receiver's resources that have the specified file extension anExtension and lie within the specified subdirectory aSubDirPath.

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

The following shows examples of invoking this method with various parameters for the bundle depicted in the class description.

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" }

Parameters:
anExtension - extension of the resource
aSubDirPath - the directory where it is searched
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
See Also:
resourcePathsForDirectories(String, String), resourcePathsForLocalizedResources(String, String)

toString

public String toString()
The string returned includes the receiver's 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.

Overrides:
toString in class Object
Returns:
String giving details of this NSBundle object
See Also:
bundleClassPackageNames(), name()
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
Last updated Mon Oct 13 15:42:52 PDT 2003.
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2003 Apple Computer, Inc.