int printRecords(IXRecordManager *aSource,const char *anAttribute, void *aKey, unsigned aLength){IXPostingList *theList;IXPostingCursor *aCursor;int i, count;
Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| IXPostingList |
| Inherits From: | List : Object | |
| Conforms To: | IXPostingExchange NXTransport | |
| Declared In: | indexing/IXPostingList.h |
| Class Description |
| IXPostingList is a subclass of List tailored for use with objects, or records, stored in an archiving object, called the source. (Generally the source is an IXRecordManager, which can use a different form of archiving from the standard read: and write: methods--the processes of archiving and unarchiving are referred to as passivation and activation in this case.) Records are activated on demand, and their persistent identifiers are accessible as postings. IXPostingList can exchange postings with instances the IXPostingCursor and IXPostingSet classes, or any other object that conforms to the IXPostingExchange protocol.
Initially, an IXPostingList stores persistent record identifiers in the form of postings (see "Associative Access" in the chapter introduction). The records themselves reside in a store managed by some other object, called the source. A source is any object that conforms to the IXRecordReading protocol. When the IXPostingList is asked for an object, it has the source activate the object, returns the objects's id, and caches the id in case it's needed again. This cache of ids remains aligned with the postings: if the postings are replaced, or moved around by insertion or deletion, the ids are replaced, or moved around with them. Objects can also be added or replaced directly, as with a List; objects added or replaced without postings are assigned null handles and weights. Note: If your code needs to iterate over all of the objects in a large IXPostingList, be sure to start with the last object in the list. An IXPostingList dynamically grows its cache of ids; asking for the last object first will cause space to be immediately allocated for all of the ids. This avoids cache resizing as the objects are requested. A common use for an IXPostingList is iterating over the records described by a set of postings; the simple function listed below prints out descriptions for records stored in an IXRecordManager. It also shows how an IXPostingList can gets its postings directly from another object, in this case an IXPostingCursor. |
int printRecords(IXRecordManager *aSource,
const char *anAttribute, void *aKey, unsigned aLength)
{
IXPostingList *theList;
IXPostingCursor *aCursor;
int i, count;
count = 0;
// get a cursor on the attribute and position it
aCursor = [aSource cursorForAttributeNamed:anAttribute];
if ([aCursor setKey:aKey andLength:aLength])
{
// load a posting list from the cursor
if (theList = [[IXPostingList alloc]
initWithSource:aSource andPostingsIn:aCursor])
{
// get space for all the object ids right away.
count = [theList count];
[theList objectAt:count - 1];
// print out the description of each activated record.
for (i = 0; i < count; i++)
printf("%s\n", [[theList objectAt:i] description];
}
}
[aCursor free];
[[theList freeObjects] free];
return count;
}
| Instance Variables |
| unsigned int maxPointers;
id <IXRecordReading> recordSource; struct IXPosting *postingList; |
| maxPointers | The number of slots allocated for object ids. | |
| recordSource | The object which stores the records kept in the IXPostingList. | |
| postingList | The handle/weight pairs in the IXPostingList. |
| Adopted Protocols |
| IXPostingExchange |  setCount:andPostings: |
| getCount:andPostings: |
| NXTransport | encodeRemotelyFor:freeAfterEncoding:isBycopy: |
| encodeUsing: decodeUsing: |
| Method Types |
| Initializing an IXPostingList | initWithSource: |
| initWithSource:andPostingsIn: |
| Retrieving the source | source | |
| Manipulating objects by handle | addHandle:withWeight: |
| insertHandle:withWeight:at: replaceHandleAt:with:weight: |
| Manipulating objects by id | addObject:withWeight: |
| insertObject:withWeight:at: replaceObjectAt:with:weight: |
| Manipulating objects by index | indexForHandle: |
| handleOfObjectAt: weightOfObjectAt: |
| Sorting the contents | sortByWeightAscending: |
| sortBySelector:ascending: |
| Instance Methods |
| addHandle:withWeight: |
| addHandle:(unsigned int)aHandle withWeight:(unsigned int)aWeight |
| Inserts aHandle with aWeight at the end of the IXPostingList. The object identified in the IXPostingList's source by aHandle can be retrieved by id with objectAt:. Returns self.
See also: |
| addObject:withWeight: |
| addObject:anObject withWeight:(unsigned int)aWeight |
| Inserts anObject with aWeight at the end of the IXPostingList, and returns self. anObject is added to the IXPostingList with no handle; addHandle:withWeight: should be used instead of this method whenever possible, in order to store a valid handle for every record.
Note: This method currently allows nil to be added to the list. This isn't recommended, and may be disallowed in a future release. See also: |
| getCount:andPostings: |
| getCount:(unsigned int *)count andPostings:(IXPosting **)thePostings |
| Returns by reference the number of postings, and a copy of the postings sorted by handle. The sender of this message is responsible for freeing the postings when they are no longer needed. Returns self.
Since objects can be added to an IXPostingList by id instead of by handle, or inserted in any order, an IXPostingList's set of postings may not conform to the requirements imposed by the IXPostingExchange protocol (that is, sorted by handle and containing no null handles). In a future release, IXPostingList may sort its postings by handle and remove null handles when returning the postings with this method. See also: |
| handleOfObjectAt: |
| (unsigned int)handleOfObjectAt:(unsigned int)index |
| Returns the handle of the posting at index if there is a posting there and it has a valid handle. If index is greater than or equal to the number of postings in the list, or if the object was entered into the list by id instead of by handle, this method returns 0.
See also: |
| indexForHandle: |
| (unsigned int)indexForHandle:(unsigned int)handle |
| Returns the position in the IXPostingList of the posting identified by handle, or NX_NOT_IN_LIST if that posting isn't in the IXPostingList.
See also: |
| initWithSource: |
| initWithSource:(id <IXRecordReading>)aSource |
| Initializes the receiver, a newly allocated IXPostingList, with aSource providing record activation. aSource should be an object that conforms to the IXRecordReading protocol, for example, an IXRecordManager. The IXPostingList initially contains no postings. Returns self.
See also: |
| initWithSource:andPostingsIn: |
| initWithSource:(id <IXRecordReading>)aSource |
| andPostingsIn:(id <IXPostingExchange>)anObject |
| Initializes the receiver, a newly allocated IXPostingList, with aSource providing record activation, and anObject providing an initial set of postings (this will usually be an IXPostingCursor or IXPostingSet). anObject should have the same source as the IXPostingList of this message. This is the designated initializer for the IXPostingList class. Returns self.
See also: |
| insertHandle:withWeight:at: |
| insertHandle:(unsigned int)aHandle |
| withWeight:(unsigned int)aWeight at:(unsigned int)index |
| Inserts aHandle with aWeight at position index in the IXPostingList, moving existing postings down one slot, if necessary. If index is equal to the number of postings in the IXPostingList, aHandle is added at the end. The insertion fails, and this method returns nil, if index is greater than the number of postings in the list or if aHandle is 0.
If the insertion is successful, returns self; if not, returns nil. See also: |
| insertObject:withWeight:at: |
| insertObject:anObject |
| withWeight:(unsigned int)aWeight at:(unsigned int)index |
| Inserts anObject with aWeight at position index in the IXPostingList, moving existing objects down one slot, if necessary. If index is equal to the number of postings in the IXPostingList, anObject is added at the end. The insertion fails, and this method returns nil, if index is greater than the number of postings in the IXPostingList. anObject is inserted into the list with no handle; insertHandle:withWeight:at: should be used instead of this method whenever possible, in order to store a valid handle for every record.
If the insertion is successful, returns self; if not, returns nil. See also: |
| replaceHandleAt:with:weight: |
| replaceHandleAt:(unsigned int)index |
| with:(unsigned int)aHandle weight:(unsigned int)aWeight |
| Replaces the posting at index with a posting made from aHandle and aWeight. The replacement fails, and this method returns nil, if index is greater than or equal to the number of postings in the IXPostingList or if aHandle is 0.
If the replacement is successful, returns self; if not, returns nil. See also: |
| replaceObjectAt:with:weight: |
| replaceObjectAt:(unsigned int)index |
| with:anObject weight:(unsigned int)aWeight |
| Replaces the object and its posting at index with anObject and a posting with a handle of 0 and weight of aWeight. The replacement fails, and this method returns nil, if index is greater than or equal to the number of postings in the IXPostingList, or if anObject is nil. anObject is inserted with no handle; your code should use replaceHandleAt:with:weight: whenever possible, in order to store a valid handle for every posting.
If the replacement is successful, returns self; if not, returns nil. See also: |
| sortBySelector:ascending: |
| sortBySelector:(SEL)aSelector ascending:(BOOL)flag |
| Sorts the contents of the IXPostingList by constructing a key from the value each record returns when aSelector is sent to it. If flag is YES, the sort is ascending (ABCD...), if flag is NO, the sort is descending (ZXYW...). Returns self.
The sort ordering used is determined by the return type of aSelector. The IXPostingList determines which of the standard Indexing Kit comparator functions to use, and applies the appropriate function to the result of each message send. However, unlike the keys of an IXBTree, the data being compared doesn't have to be inline (serialized); the return value of aSelector can be a pointer type, and the IXPostingList will construct a proper key for it. See the IXComparisonSetting protocol specification for more information on legal comparison values. See also: |
| sortByWeightAscending: |
| sortByWeightAscending:(BOOL)flag |
| Sorts the contents of the IXPostingList based on the weight of each record. If flag is YES, the sort is from low weight to high, if flag is NO, the sort is from high weight to low.
See also: |
| source |
| (id <IXRecordReading>)source |
| Returns the object which provides storage for the records referenced by the IXPostingList.
See also: |
| weightOfObjectAt: |
| (unsigned int)weightOfObjectAt:(unsigned int)index |
| Returns the weight of the posting at index, or 0 if index is greater than or equal to the number of postings in the IXPostingList.
See also: |