uicc.contactmanager
Interface FieldDescriptorsListView


public interface FieldDescriptorsListView

A field descriptors list holds all field descriptors defined for a contact manager.

It defines all fields that any contact shall have. Therefore, it represents the structure of all contacts.

The field descriptors list shall be setup before any contact has been created in the contact manager.

Within a descriptors list, each field descriptor is assigned a numeric identifier, that is unique within the list.
The identifier for each field descriptor is assigned by the containing field descriptors list and is only significant within the parent contact manager.

An object that realizes the FieldDescriptorsListView interface represents a field descriptors list.
It represents the same field descriptors list since its creation, during its whole lifetime.

Each FieldDescriptorsListView instance provides an independent enumeration scheme to enumerate all field descriptors that belong to the list.

FieldDescriptorsListView instances also provide a factory method to create an instance of the FieldDescriptorView interface.

Multiple FieldDescriptorsListView instances may be created by the same or different applications. Although they may represent the same descriptors list, each of them has its own state.
This particularly applies to the current enumeration progress, which is specific to each instance.


Method Summary
 int addFieldDescriptor(FieldDescriptorView fieldDescriptorView)
           Adds a field descriptor to the field descriptors list.
 FieldDescriptorView createFieldDescriptorViewInstance()
           Factory method used to create an instance of the FieldDescriptorView interface.
 int getNumberOfFieldDescriptors()
          Returns the number of field descriptors in the list.
 boolean hasMoreFieldDescriptors()
           Checks if there are more field descriptors in the current enumeration.
 void removeFieldDescriptor(int fieldDescriptorIdentifier)
           Removes a field descriptor from the field descriptors list.
 void selectFieldDescriptor(FieldDescriptorView fieldDescriptorView, int fieldDescriptorIdentifier)
           Binds a FieldDescriptorView instance to the descriptor that matches the provided fieldDescriptorIdentifier.
 int selectNextFieldDescriptor(FieldDescriptorView fieldDescriptorView)
           Binds a FieldDescriptorView instance with the next descriptor in the current enumeration.
 void startEnumeration()
           Starts a new enumeration of all field descriptors in the list.
 

Method Detail

createFieldDescriptorViewInstance

FieldDescriptorView createFieldDescriptorViewInstance()

Factory method used to create an instance of the FieldDescriptorView interface.

The instance is initially created in the DESELECTED state.
See the description of the FieldDescriptorView interface for detailed information about its complete life cycle.

The new instance is owned by the calling application.

Returns:
new FieldDescriptorView instance

startEnumeration

void startEnumeration()

Starts a new enumeration of all field descriptors in the list.


hasMoreFieldDescriptors

boolean hasMoreFieldDescriptors()

Checks if there are more field descriptors in the current enumeration.

Returns:
true if there is at least one more descriptor in the current enumeration

selectNextFieldDescriptor

int selectNextFieldDescriptor(FieldDescriptorView fieldDescriptorView)

Binds a FieldDescriptorView instance with the next descriptor in the current enumeration.

The order in which the descriptors are enumerated is unspecified.

After successful operation, the FieldDescriptorView instance is in the SELECTED state, and is bound to the next descriptor in the current enumeration.

If the current enumeration has not been started, or already reached its end, or after unsuccessful operation for any reason, the FieldDescriptorView instance is in DESELECTED state.

Parameters:
fieldDescriptorView - FieldDescriptorView instance to bind to the next descriptor in the enumeration.
Returns:
descriptor identifier, or -1 if the current enumeration reached its end.

selectFieldDescriptor

void selectFieldDescriptor(FieldDescriptorView fieldDescriptorView,
                           int fieldDescriptorIdentifier)

Binds a FieldDescriptorView instance to the descriptor that matches the provided fieldDescriptorIdentifier.

After successful operation, the FieldDescriptorView instance is in SELECTED state, and is bound to the selected descriptor.

After unsuccessful operation, the FieldDescriptorView instance is in DESELECTED state.

Parameters:
fieldDescriptorView - FieldDescriptorView instance to bind with the next descriptor that matches the identifier.
fieldDescriptorIdentifier - descriptor identifier of the field descriptor to get
Throws:
uicc.contactmanager.ContactManagerException: -
  • with reason WRONG_IDENTIFIER if the list contains no descriptor with the fieldDescriptorIdentifier provided.

addFieldDescriptor

int addFieldDescriptor(FieldDescriptorView fieldDescriptorView)

Adds a field descriptor to the field descriptors list.

The descriptor to be added is represented by an instance of FieldDescriptorView that is in DESELECTED state, whose attributes have been set to the appropriate values.

When a descriptor is added to a descriptors list, any enumeration over the same descriptors list currently in progress may or may not include the new descriptor, depending on the implementation.

After successful completion of this operation, the FieldDescriptorView instance is in SELECTED state, and is bound to the newly created descriptor.

Parameters:
fieldDescriptorView - A FieldDescriptorView instance with attributes set according to appropriate values.
Returns:
the new descriptors's identifier

removeFieldDescriptor

void removeFieldDescriptor(int fieldDescriptorIdentifier)

Removes a field descriptor from the field descriptors list.

This method fails in the following cases:

Parameters:
fieldDescriptorIdentifier - identifier of the field descriptor to be removed from the list
Throws:
uicc.contactmanager.ContactManagerException - with the following reasons:
  • WRONG_IDENTIFIER if fieldDescriptorIdentifier does not identify any descriptpor in the field descriptors list.
  • ITEM_SELECTED if the descriptor to be removed is currently selected by a FieldDescriptorView instance.
  • ENUMERATION_IN_PROGRESS if a conflicting enumeration is currently in progress.

getNumberOfFieldDescriptors

int getNumberOfFieldDescriptors()
Returns the number of field descriptors in the list.

Returns:
number of field descriptors