com.novell.application.console.snapin
Interface VirtualObjectEntryEnumeration

All Superinterfaces:

BrowserObjectEntryEnumeration, java.util.Enumeration, ObjectEntryEnumeration

All Known Implementing Classes:

DefaultVirtualObjectEntryEnumeration

public interface VirtualObjectEntryEnumeration

extends BrowserObjectEntryEnumeration

Provides a virtual ObjectEntry enumeration.

A virtual ObjectEntry enumeration may be implemented to provide virtual access to ObjectEntries returned from a namespace. The implementation of the enumeration must support relative approximate positions in the enumeration and an approximate total count of ObjectEntries in the enumeration.

The implementation must also support an enumeration cursor position. This is a relative approximate position in the enumeration and is fully explained in the comments of the getCurrentPosition() method.

Throughout the comments in this class, implementation index refers to specific ObjectEntry indexes in theoretical implementations of the VirtualObjectEntry interface. These indexes differ from the enumeration cursor position. The enumeration cursor position is the position that the enumeration consumer receives when calling methods of this interface. The implementation index refers to the private index of an ObjectEntry in an implementation of VirtualObjectEntryEnumeration

Field Summary

static int	VENUMPOS_AFTERENUM The enumeration cursor position is after the end of the enumeration.
static int	VENUMPOS_BEFOREENUM The enumeration cursor position is before the start of the enumeration.
static int	VENUMPOS_FIRSTENTRY The enumeration cursor position is on the first entry in the enumeration.

Method Summary

int	getCount() Get the approximate total enumeration entry count.
int	getCurrentPosition() Returns the current enumeration cursor position.
int	getLastEntryPosition() Returns the enumeration cursor position for the last entry in the enumeration.
ObjectEntry[]	getNext(int count) Returns the next count entries in the enumeration.
ObjectEntry[]	getPrev(int count) Returns the previous entries in the enumeration, as indicated by the count.
int	moveLeft(int count) Moves the enumeration cursor position toward the left in the enumeration.
int	moveRight(int count) Moves the enumeration cursor position toward the right in the enumeration.
int	moveTo(int position) Moves the enumeration cursor position to the entry associated with the position specified in the enumeration.

Methods inherited from interface com.novell.application.console.snapin.BrowserObjectEntryEnumeration

moveFirst, moveLast, moveTo, previous, refresh, setBlockSize

Methods inherited from interface com.novell.application.console.snapin.ObjectEntryEnumeration

next

Methods inherited from interface java.util.Enumeration

hasMoreElements, nextElement

Field Detail

VENUMPOS_AFTERENUM

public static final int VENUMPOS_AFTERENUM

The enumeration cursor position is after the end of the enumeration.

The constant value is -2.

See Also:

Constant Field Values

VENUMPOS_BEFOREENUM

public static final int VENUMPOS_BEFOREENUM

The enumeration cursor position is before the start of the enumeration.

The constant value is -1.

See Also:

Constant Field Values

VENUMPOS_FIRSTENTRY

public static final int VENUMPOS_FIRSTENTRY

The enumeration cursor position is on the first entry in the enumeration.

The constant value is 0. The enumeration cursor position for the last entry in the enumeration is obtained by calling the method getLastEntryPosition().

See Also:

Constant Field Values

Method Detail

getCount

public int getCount()
             throws SnapinException

Get the approximate total enumeration entry count.

Returns:

The approximate total enumeration entry count.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

getCurrentPosition

public int getCurrentPosition()
                       throws SnapinException

Returns the current enumeration cursor position.

The enumeration cursor position is defined as one of the following:

Given that LASTENTRYPOS is the value returned from the method getLastEntryPosition().

• VENUMPOS_BEFOREENUM = before start of the enumeration
• VENUMPOS_FIRSTENTRY = on first entry in the enumeration
• VENUMPOS_FIRSTENTRY to LASTENTRYPOS = approximatly this position into the enumeration
• LASTENTRYPOS = on last entry in the enumeration
• VENUMPOS_AFTERENUM = after last entry in the enumeration

Position values between VENUMPOS_FIRSTENTRY and LASTENTRYPOS indicate a relative approximate position in the enumeration.

Returns:

The current enumeration cursor position.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

getLastEntryPosition

public int getLastEntryPosition()
                         throws SnapinException

Returns the enumeration cursor position for the last entry in the enumeration.

This method allows implementations of VirtualObjectEntryEnumeration to decide the granularity of positioning to provide. The first entry enumeration cursor position is assumed to be zero, but the last entry enumeration cursor position is left to the implementation.

This method always returns the same enumeration cursor position for the last entry during the entire lifetime of the enumeration.

Returns:

The enumeration cursor position for the last entry in the enumeration.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

getNext

public ObjectEntry[] getNext(int count)
                      throws SnapinException

Returns the next count entries in the enumeration.

Get the number entries toward the right (end) of the enumeration, as indicated in the count, and move the current enumeration cursor position toward the right of the enumeration.

The movement rules are as follow:

The starting index refers to the implementation index before the getNext() was executed. The ending index refers to the implementation index after the getNext() is executed. A returned entry is an entry in the array returned from getNext().

1. If the starting index is somewhere in the enumeration, the returned entries are defined by including the entry pointed at by the starting index plus the next count-1 entries to the right of the starting index entry. For example, given implementation indexes 0 thru 10, if the starting index is 4 and getNext(3) is executed, the ending index will be 7. The returned entries will be 4, 5, and 6.
2. If the end of the enumeration is encountered before the count is expired, the ending index is set to VENUMPOS_AFTERENUM, and the returned entries are defined by including the entry pointed at by the starting index and each subsequent entry in the enumeration including the last entry. For example, given implementation indexes 0 thru 5, where 5 is the last entry, if the starting index is 4 and getNext(3) is executed, the ending index will be VENUMPOS_AFTERENUM. The returned entries will be 4 and 5. This situation will not throw an exception.
3. If the starting index is the last entry in the enumeration, the ending index is set to VENUMPOS_AFTERENUM, and a count of one is returned. This is a subset of rule 2.
4. If the starting index is VENUMPOS_BEFOREENUM, the starting index is automatically positioned to the first entry in the enumeration, and getNext() is executed as described in rule 1.

5. If the starting index is VENUMPOS_AFTERENUM, the enumeration cursor position does not change, and a new ObjectEntry[0] is returned.

Always return an ObjectEntry[] with the correct number of entries. Do not return a new ObjectEntry[count] with nulls padding the unavailable entries.

Parameters:

count - The count of next entries to be returned

Returns:

The array of next ObjectEntries.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

getPrev

public ObjectEntry[] getPrev(int count)
                      throws SnapinException

Returns the previous entries in the enumeration, as indicated by the count.

Gets entries toward the left (start) of the enumeration, as indicated by the count, and moves the current enumeration cursor position toward the left of the enumeration.

The movement rules are as follows:

The starting index refers to the implementation index before the getPrev() was executed. The ending index refers to the implementation index after the getPrev() is executed. A returned entry is an entry that is a member of the array returned from getPrev().

1. If the starting index is somewhere in the enumeration, the returned entries are defined by excluding the entry pointed at by the starting index, moving one index to the left, and including the current entry plus the next count-1 entries. The ending index will be the index of the leftmost entry in the returned entry array. For example, given implementation indexes 0 thru 10, if the starting index is 8 and getPrev(3) is executed, the ending index will be 5. The returned entries will be 5, 6, and 7.
2. If the start of the enumeration is encountered before the count is expired, the ending index is set to VENUMPOS_BEFOREENUM, and the returned entries are defined by excluding the entry pointed at by the starting index and including each subsequent entry in the enumeration, including the first entry. For example, given implementation indexes 0 thru 5, where 5 is the last entry, if the starting index is 2 and getPrev(3) is executed, the ending index will be VENUMPOS_BEFOREENUM. The returned entries will be 0 and 1. This situation will not throw an exception.
3. If the starting index is the first entry in the enumeration, the ending index is set to VENUMPOS_BEFOREENUM, and the returned entries will be ObjectEntry[0].
4. If the starting index is VENUMPOS_AFTERENUM, the returned entries are defined by moving the enumeration cursor position to the last entry in the enumeration, including the last entry, plus count-1 entries to the left. The VENUMPOS_AFTERENUM entry is ignored and the last count entries in the enumeration are returned. The ending implementation index is the index of the leftmost returned entry.
5. If the starting index is VENUMPOS_BEFOREENUM, the enumeration cursor position does not change, and a new ObjectEntry[0] is returned.

Always return an ObjectEntry[] with the correct number of entries. Do not return a new ObjectEntry[count] with nulls padding the "unavailable" entries.

Parameters:

count - The count of previous entries to be returned

Returns:

The array of previous ObjectEntrys.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

moveLeft

public int moveLeft(int count)
             throws SnapinException

Moves the enumeration cursor position toward the left in the enumeration.

Moves the cursor position toward the left (start) of the enumeration according to the count specified.

The movement rules are as follows:

The starting index refers to the implementation index before the moveRight() was executed. The "ending index" refers to the implementation index after the moveRight() is executed.

1. If the starting index is somewhere in the enumeration, move left the number of times indicated in the count. For example, given implementation indexes 0 thru 10. If the current implementation index is 8 and moveLeft(3) is executed, the new implementation index will be 5 and a count of 3 will be returned.
2. If the beginning of the enumeration is encountered before the count is expired, the ending index is set to VENUMPOS_BEFOREENUM, and the returned count is equal to the starting index minus the implementation index of the first entry in the enumeration. For example, given implementation indexes 0 thru 5, where 0 is the first entry, if the current implementation index is 2 and moveLeft(3) is executed, the new enumeration cursor position will be VENUMPOS_BEFOREENUM and a count of 2 will be returned.
3. If the starting index is the first entry in the enumeration, the ending index is set to VENUMPOS_BEFOREENUM, and a count of zero is returned.
4. If the starting index is VENUMPOS_AFTERENUM, the ending index is set to the implementation index of the last entry, minus the count, plus one. For example, given entries n, n+1, n+2, where n+2 is the last entry in the enumeration, if the starting index is VENUMPOS_AFTERENUM and moveLeft(2) is executed, the ending index will be n+1, and a count of 2 will be returned.

Parameters:

count - The count of entries to move.

Returns:

The count of entries actually moved.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

moveRight

public int moveRight(int count)
              throws SnapinException

Moves the enumeration cursor position toward the right in the enumeration.

Moves the cursor toward the right (end) of the enumeration according to the count specified.

The movement rules are as follows:

The starting index indicates the implementation index before the moveRight() was executed. The "ending index" means the implementation index after the moveRight() is executed.

1. If the starting index is somewhere in the enumeration, move left the number of times indicated in the count. For example, given implementation indexes 0 thru 10. If the starting index is 4 and moveRight(3) is executed, the ending index will be 7 and a count of 3 will be returned.
2. If the end of the enumeration is encountered before the count is expired, the ending index is set to VENUMPOS_AFTERENUM, and the returned count is equal to the implementation index of the last enumeration entry minus the starting index plus one. For example, given implementation indexes 0 thru 5, where 5 is the last entry, if the starting index is 4 and moveRight(3) is executed, the ending index will be VENUMPOS_AFTERENUM and a count of 2 will be returned.
3. If the starting index is the last entry in the enumeration, the ending index is set to VENUMPOS_AFTERENUM, and a count of one is returned. This is a subset of rule 2.
4. If the starting index is VENUMPOS_BEFOREENUM, the starting implementation index is automatically positioned to the first entry in the enumeration, and moveLeft() is executed as described in rule 1.

Parameters:

count - The count of entries to move.

Returns:

The count of entries actually moved.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

moveTo

public int moveTo(int position)
           throws SnapinException

Moves the enumeration cursor position to the entry associated with the position specified in the enumeration.

The returned enumeration cursor position is an approximate position in the enumeration as described in the comments for getCurrentPosition().

Parameters:

position - The relative position based on percentage from 0-1000 where 1000 is 100%.

Returns:

The new enumeration cursor position.

Throws:

SnapinException - Thrown by the service provider when an error occurs.

See Also:

getCurrentPosition()