|
PDAP Public Review Draft | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Represents the common interfaces of an element for a PIM database. A PIM element is a container that references its data through fields. A PIM element is created from a particular PIM list and is associated with that list for the life of the element. The element takes on the field characteristics of the list that is it created or retrieved from; that is, the list dictates what fields that this element contains.
Field are referenced through fields IDs assigned by the implementing class to each piece of data that can be stored in a PIM element. This field ID is used to set the data and to retrieve the data.
The implementing class assigns and expects a data type for the data
associated with a field ID. The data type for a field ID can be retrieved
through getFieldDataType(int)
.
Additionally, a human readable label is also assigned to each field.
The label can be retrieved through getFieldLabel(int)
.
PIM elements may be assigned to categories, depending on the implementing PIM list class that the element is associated with. Categories are arbitrary named groupings of elements within a list. The list determines if categories can be assigned, and how many categories can be assigned per element.
PIM elements can have its data imported and exported using standard byte based formats. Each implementing class defines what formats can be imported and exported for that element.
An element contains three types of data:
Some named fields also have a further defining type ID associated with them. This allows for the appearance of more than one instance of a field.
Extended fields are fields that does not have a specific field explicitly predefined
in the API, but do have field ids assigned by the contact list. These fields
are implementation dependent and can vary. Users can find out a field id is
is extended field through the method PIMList.isExtendedField(int)
. Users
can also find out the data type for the field (getFieldDataType(int)
)
and the human readable label for the field (getFieldLabel(int)
).
Extended fields use the same get and set methods as named fields.
Categories are string items that may correspond to categories values already existing in the PIMElement's associated PIMList.
Field Summary | |
static int |
BINARY
Data type ID indicating data is binary (in a byte array). |
static int |
DATE
Data type ID indicating data is a Date. |
static int |
INT
Data type ID indicating data is an integer. |
static int |
STRING
Data type ID indicating data is a String. |
static int |
TYPED_STRING
Data type ID indicating data is a String with a further qualifying integer type. |
Method Summary | |
void |
addToCategory(java.lang.String category)
Adds a category to this element. |
void |
commit()
This method persists the data in the element to its PIM list. |
void |
fromSerialFormat(Reader reader)
Initializes a Element from information contained in a stream of Unicode characters. |
byte[] |
getBinary(int fieldID)
Get binary data for a field from the Element. |
java.lang.String[] |
getCategories()
Returns all the categories for that the Element belongs to. |
long |
getDate(int fieldID)
Get a Date field from the Element. |
int |
getFieldDataType(int fieldID)
Returns an int representing the data type of the data associated with the given field ID. |
java.lang.String |
getFieldLabel(int fieldID)
Returns a String label associated with the given field ID. |
int[] |
getFields()
Returns all field IDs in the element that have data stored for them. |
int |
getInt(int fieldID)
Get an integer field from the Element. |
PIMList |
getPIMList()
Returns the PIMList associated with this element. |
java.lang.String |
getString(int fieldID)
Get a String field from the Element. |
java.lang.String |
getTypedString(int fieldID,
int typeID)
Get a String field with a specific type in the element. |
boolean |
isModified()
This method returns a boolean indicating whether any of this element's fields have been modified since the element was retrieved or last committed. |
int |
maxCategories()
Returns the maximum number of categories that this element can be assigned to. |
void |
removeFromCategory(java.lang.String category)
Remove a category from this Element. |
void |
setBinary(int fieldID,
byte[] data)
Set a binary data field for the Element. |
void |
setDate(int fieldID,
long value)
Set a Date field in the Element. |
void |
setInt(int fieldID,
int value)
Set an integer field in the Element. |
void |
setString(int fieldID,
java.lang.String value)
Set a String field in the Element. |
void |
setTypedString(int fieldID,
int typeID,
java.lang.String value)
Set a String field with a specific type ID in the element. |
java.lang.String[] |
supportedSerialVersions()
This method returns the versions supported for the data format used on converting this element's data to and from a serial format. |
void |
toSerialFormat(Writer writer)
Writes the data from this element as a stream of Unicode characters into the provided Writer object. |
void |
toSerialFormat(Writer writer,
java.lang.String version)
Writes the data from this element as a stream of Unicode characters into the provided Writer object. |
Field Detail |
public static final int BINARY
BINARY
is
retrieved via getBinary(int)
and set via setBinary(int, byte[])
.BINARY
.public static final int DATE
DATE
is
retrieved via getDate(int)
and set via setDate(int, long)
.DATE
.public static final int INT
INT
is
retrieved via getInt(int)
and set via setInt(int, int)
.INT
.public static final int STRING
getString(int)
and set via setString(int, java.lang.String)
.STRING
.public static final int TYPED_STRING
TYPED_STRING
is
retrieved via getTypedString(int, int)
and set via setTypedString(int, int, java.lang.String)
.TYPED_STRING
.Method Detail |
public PIMList getPIMList()
public void commit() throws PIMException
PIMList.getCategories()
.
In this case the categories will be dropped silently when this method
is invoked (this allows data imported using fromSerialFormat(java.io.Reader)
to be persisted).PIMException
- if the commit encounters an error and cannot
complete.SecurityException
- if the application has not been granted
write access to the PIM list.public boolean isModified()
public int getFieldDataType(int fieldID) throws PIMException
fieldID
- The ID of the field for which the data type is being
queried.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public java.lang.String getFieldLabel(int fieldID) throws PIMException
fieldID
- The ID of the field for which the label is being
queried.java.lang.IllegalArgumentException
- if the field ID is not valid
for the implementing class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public int[] getFields()
public byte[] getBinary(int fieldID) throws PIMException
fieldID
- The ID of the field to get.null
to indicate the field has not been set. The value is
an inline binary data representation
in a "B" binary encoded string as defined by [IETF RFC 2047].java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void setBinary(int fieldID, byte[] data) throws PIMException
fieldID
- The ID of the field to set.data
- The data to set the field to. Setting a field to null
has the
effect of clearing the field. The data is an inline binary data
representation and must be in a "B" binary encoded string as defined
by [IETF RFC 2047].java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public long getDate(int fieldID) throws PIMException
fieldID
- The field ID to get.null
to indicate the field has not been set.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void setDate(int fieldID, long value) throws PIMException
fieldID
- The field ID to set.value
- The value to set the field to. Setting a field to 0 has the
effect of clearing it.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public int getInt(int fieldID) throws PIMException
fieldID
- The field ID to get.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void setInt(int fieldID, int value) throws PIMException
fieldID
- The field ID to set.value
- The value to set the field to.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public java.lang.String getString(int fieldID) throws PIMException
fieldID
- The field ID to get.null
to indicate the field has not been set.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void setString(int fieldID, java.lang.String value) throws PIMException
fieldID
- The field ID to set.value
- The value to set the field to. Setting a field to null
has the
effect of clearing it.java.lang.IllegalArgumentException
- if the field ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public java.lang.String getTypedString(int fieldID, int typeID) throws PIMException
fieldID
- The field ID to get.typeID
- The specific type for the field to retrieve.null
to indicate the field/type has not been set.java.lang.IllegalArgumentException
- if the field ID or type ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void setTypedString(int fieldID, int typeID, java.lang.String value) throws PIMException
fieldID
- The field ID to set.typeID
- The type ID for the field.value
- The value to set the field to. Setting a field to null
has the
effect of clearing it.java.lang.IllegalArgumentException
- if the field ID or type ID is not valid
for the derived class.PIMException
- if the field ID is not supported in the implementing
instance of the class.public void addToCategory(java.lang.String category) throws PIMException
PIMList.getCategories()
from the list associated with this
element. Some devices may not allow categories to
be added which are not in the list returned from PIMList.getCategories()
.
In this case a PIMException
may be thrown.
The category names are case sensitive in the javax.microedition.pim package.category
- the category to addjava.lang.IllegalArgumentException
- if category is null
PIMException
- may be thrown if category is not in the list's category list
and the list prevents that condition from occurring. Also thrown
if categories are not supported in the implementation.public void removeFromCategory(java.lang.String category)
category
- the category to removejava.lang.IllegalArgumentException
- if category is null
public java.lang.String[] getCategories()
public int maxCategories()
public void fromSerialFormat(Reader reader) throws PIMException
reader
- a character stream contained in a java.io.Reader object.PIMException
- If the data is incorrect, or does not contain enough information.java.lang.IllegalArgumentException
- if reader
is null
.public void toSerialFormat(Writer writer) throws PIMException
writer
- the Writer object that this element is written to as
a character stream.PIMException
- if an error occurs when coverting the Element's data
preventing the element's data from completely being written. There
is no guarantee that the Writer will be unmodified or contain
incomplete information if this exception is thrown.java.lang.IllegalArgumentException
- if writer is null
.public void toSerialFormat(Writer writer, java.lang.String version) throws PIMException
writer
- the Writer object that this element is written to as
a character stream.version
- the requested version of the data format to usePIMException
- if an error occurs when coverting the Element's data
preventing the element's data from completely being written. There
is no guarantee that the Writer will be unmodified or contain
incomplete information if this exception is thrown. Also thrown
if the provided version is not supported by the implementation.java.lang.IllegalArgumentException
- if writer is null
or version
is null
.public java.lang.String[] supportedSerialVersions()
toSerialFormat(java.io.Writer, String)
.
|
PDAP 1.0 Spec, Rev. 0.16 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |