FRAMEWORK The Foundation Framework Package: com.webobjects.foundation Introduction The Foundation Framework defines a base layer of classes written in Java. In addition to providing a set of useful primitive object classes, it introduces several paradigms that define functionality not covered by the Java language. The Foundation Framework is designed with these goals in mind: I Provide a small set of basic utility classes I Simplifies software development by introducing consistent conventions for things such as notifications, object persistence, key-value coding, and validation. I Provide a level of OS independence, to enhance portability This version of the Foundation framework is similar to the WebObjects 4.5 Foundation framework (com.apple.yellow.foundation) but does not rely on the Java Bridge because it is written in pure Java. The API for the pure Java Foundation also follows conventions in Sun’s API more closely than the WebObjects 4.5 Foundation. The pure Java Foundation resembles the WebObjects 4.5 Java Client Foundation (com.apple.client.foundation) but provides a larger set of functions. Foundation Framework Classes The Foundation Framework consists of several related groups of classes as well as a few individual classes: I Data storage. NSData provides object-oriented storage for arrays of bytes. NSArray, NSDictionary, and NSSet provide storage for objects of any class. 1 FRAMEWORK The Foundation Framework I Dates and times. The NSTimestamp and NSTimeZone classes store times and dates. They offer methods for calculating date and time differences, for displaying dates and times in many formats, and for adjusting times and dates based on location in the world. The NSTimestampFormatter class converts dates to user-presentable strings and back. I Application coordination and timing. NSNotification and NSNotificationCenter provide systems that an object can use to notify all interested observers of changes that occur. NSDelayedCallbackCenter coordinates events. I Object distribution and persistence. The data that an object contains can be represented in an architecture-independent way using NSCoder and its subclasses, which also stores class information along with the data. The resulting representations are used for archiving and object distribution. I Object disposal. The NSDisposable interface together with the NSDisposableRegistry ensure that unused objects are collected by Java’s garbage collector. I Key-value coding. The NSKeyValueCoding and NSKeyValueCodingAdditions interfaces along with their support classes provide a consistent way for objects to receive and return values for keys. I Validation. The NSValidation interface and support classes define and implement a consistent validation mechanism. I Locking of objects. The NSLock, NSRecursiveLock, and NSMultiReaderLock classes together with the NSLocking interface coordinate the locking of objects or graphs of objects. I Operating system services. Several classes are designed to insulate you from the idiosyncracies of various operating systems. NSPathUtilities provides a consistent interface for working with file system paths. NSBundle accesses the application’s resources. I Other utility classes. NSRange specifies a range of values. NSComparator defines inequality relationships between objects for sorting. NSUndoManager manages an application’s undo function. NSForwardException wraps exceptions into a subclass of Java’s RuntimeException. NSPropertyListSerialization converts between property lists and byte arrays. 2 CLASS NSArray Inherits from: Object Implements: Cloneable java.io.Serializable NSCoding NSKeyValueCoding NSKeyValueCodingAdditions Package: com.webobjects.foundation Class Description NSArray and its subclass NSMutableArray manage collections of objects called arrays. NSArray creates static arrays and NSMutableArray creates dynamic arrays. 3 CLASS NSArray Table 0-1 describes the NSArray methods that provide the basis for all NSArray’s other methods; that is, all other methods are implemented in terms of these three. If you create a subclass of NSArray, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly. Table 0-1 NSArray’s Base API Method Description count Returns the number of elements in the array. objectAtIndex Provides access to the array elements by index. objectsNoCopy Returns a natural language array containing the NSArray’s objects. The methods objectEnumerator and reverseObjectEnumerator grant sequential access to the elements of the array, differing only in the direction of travel through the elements. These methods are provided so that arrays can be traversed in a manner similar to that used for objects of other collection classes in both the Java API and the Foundation Kit, such as java.util.Hashtable or NSDictionary. See the objectEnumerator method description for a code excerpt that shows how to use these methods to access the elements of an array. NSArray provides methods for querying the elements of the array. indexOfObject searches the array for the object that matches its argument. To determine whether the search is successful, each element of the array is sent an equals message. Another method, indexOfIdenticalObject, is provided for the less common case of determining whether a specific object is present in the array. indexOfIdenticalObject tests each element in the array to see its the exact same instance as the argument. To act on the array as a whole, a variety of other methods are defined. You can extract a subset of the array (subarrayWithRange) or concatenate the elements of an array of Strings into a single string (componentsJoinedByString). In addition, you can compare two arrays using the isEqualToArray and firstObjectCommonWithArray methods. Finally, you can create new arrays that contain the objects in an existing array and one or more additional objects with arrayByAddingObject and arrayByAddingObjectsFromArray. 4 CLASS NSArray Operators An NSArray works with NSArray.Operators to perform operations on the array’s elements. By default, an array has operators defined for the following keys: Key Operator Description count Returns the number of elements in an array. max Returns the element in the array with the highest value. min Returns the element in the array with the lowest value. avg Returns the average of the array’s elements’ values. sum Returns the sum of the array’s element’s values. To compute an operation on an array’s elements, you use key-value coding methods with a specially formatted key. The character “@” introduces the name of the operator you want to perform. For example, to compute the average salary of an array’s elements, you could use the method valueForKeyPath with “@avg.salary” as the key path. For more information, see the NSArray.Operator interface specification. If you write your own operator class, you can make it available for use with NSArrays with the method setOperatorForKey. The operatorNames method returns the keys for the operators that NSArray knows about, and operatorForKey returns the operator for a specified key. 5 CLASS NSArray Constants NSArray defines the following constants: Constant Type Description AverageOperatorN String A key representing the operator (an NSArray.Operator) that ame computes the average of the elements in an array. CountOperatorNam String A key representing the operator (an NSArray.Operator) that e computes the number of elements in an array. NotFound int Returned in the place of an index when an object is not found in an array. For example, indexOfObject returns NotFound if none of the receiver’s objects are equal to the specified object. MaximumOperatorN String A key representing the operator (an NSArray.Operator) that ame computes the largest element in an array. MinimumOperatorN String A key representing the operator (an NSArray.Operator) that ame computes the smallest element in an array. EmptyArray NSArray An empty array, which can be shared to save memory. SumOperatorName String A key representing the operator (an NSArray.Operator) that computes the sum of the elements in an array. 6 CLASS NSArray Interfaces Implemented Cloneable clone java.io.Serializable NSCoding decodeObject classForCoder encodeWithCoder NSKeyValueCoding takeValueForKey valueForKey NSKeyValueCodingAdditions takeValueForKeyPath valueForKeyPath Method Types Creating arrays NSArray immutableClone mutableClone arrayByAddingObject 7 CLASS NSArray arrayByAddingObjectsFromArray sortedArrayUsingComparator subarrayWithRange Querying the array containsObject count getObjects indexOfObject indexOfIdenticalObject lastObject objectAtIndex objects objectsNoCopy objectEnumerator reverseObjectEnumerator vector Comparing arrays firstObjectCommonWithArray isEqualToArray Working with string elements componentsJoinedByString componentsSeparatedByString Operations operatorForKey operatorNames setOperatorForKey removeOperatorForKey 8 CLASS NSArray Methods inherited from Object equals hashCode toString Sending messages to elements makeObjectsPerformSelector Constructors NSArray public NSArray() Creates an empty, immutable array. After an immutable array has been initialized in this way, it can’t be modified. If you need an empty, immutable array, use EmptyArray instead. This method is used by mutable subclasses of NSArray. public NSArray(NSArray anArray) Creates an array containing the objects in anArray. After an immutable array has been initialized in this way, it can’t be modified. public NSArray(Object