com.hcl.domino.data

Interface Item

All Superinterfaces:

IAdaptable

public interface Item
extends IAdaptable

Carefull attention for date/time and the new Java Stuff and JNA TimeDate

Since:

0.5.0

Author:

t.b.d

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Item.ItemFlag Enum for the field flags for an Item

Method Summary

Modifier and Type	Method and Description
Item	convertRFC822TextItem() This function converts the input ItemDataType.TYPE_RFC822_TEXT item in an open document to its pre-V5 equivalent; i.e.
void	copyToDocument(Document doc, boolean overwrite) Copies this item to a new document, retaining the current name.
void	copyToDocument(Document doc, String newItemName, boolean overwrite) Copies this item to a new document, with a new Item name.
<T> T	get(Class<T> valueType, T defaultValue) Returns the item value converted to the specified data type. We currently support the following value types out of the box: String Integer Long Double DominoDateTime LocalDate LocalTime OffsetDateTime TemporalAccessor (returned as DominoDateTime) Additional value types are supported by implementing and registering DocumentValueConverter as Java services.
<T> List<T>	getAsList(Class<T> valueType, List<T> defaultValue) Returns a list of item values converted to the specified data type. We currently support the following value types out of the box: String Integer Long Double DominoDateTime LocalDate LocalTime OffsetDateTime TemporalAccessor (returned as DominoDateTime) Additional value types are supported by implementing and registering DocumentValueConverter as Java services.
Set<Item.ItemFlag>	getFlags() Gets all the field flags corresponding to the Item
Optional<MimeEntity>	getMimeEntity() Retrieves the item content as a MIME entity, if this is a MIME item.
String	getName() Gets the field name.
DocumentProperties	getProperties() Extracts the key elements available in the Notes Client Document Properties window, so they can be made available in a serializable format
int	getSequenceNumber() Incremental integer for the nth save this Item was last updated.
ItemDataType	getType() Gets the data type for a field, converting it to the more readable enum
int	getTypeValue() Gets the data type for a field, as the internal int
List<Object>	getValue() Decodes the item value(s).
int	getValueLength() Returns the value length in bytes
boolean	isEncrypted() Whether or not the Item requires additional encryption key in addition to database-level and document-level Reader access in order to see the content.
boolean	isNames() Whether or not the NAMES field flag is applied on this Item.
boolean	isProtected() Whether or not the Item prevents access if the person only has Author access to the database.
boolean	isReaders() Whether or not the READERS field flag is applied on this Item.
boolean	isReadWriters() Whether or not the READWRITERS field flag is applied on this Item.
boolean	isSigned() Whether or not the Item will be signed next time the document is saved.
boolean	isSummary() Whether or not the SUMMARY field flag is applied on this Item.
void	remove() Remove this item from the parent document
void	setEncrypted(boolean isEncrypted) Change whether or not the Item requires additional encryption key in addition to database-level and document-level Reader access in order to see the content.
void	setNames(boolean isNames) Sets the NAMES field flag on this Item.
void	setProtected(boolean isProtected) Change whether or not the Item prevents access if the person only has Author access to the database.
void	setReaders(boolean isReaders) Sets the READERS field flag on this Item.
void	setReadWriters(boolean isReadWriters) Sets the READWRITERS field flag on this Item.
void	setSigned(boolean isSigned) Change whether or not the Item will be signed next time the document is saved.
void	setSummary(boolean b) Changes the summary field flag

Methods inherited from interface com.hcl.domino.data.IAdaptable

getAdapter

Method Detail

getName

String getName()

Gets the field name. Fields beginning "$" are, by convention, system fields

Returns:

the field name as a String

getTypeValue

int getTypeValue()

Gets the data type for a field, as the internal int

Returns:

internal int value corresponding to the data type

getType

ItemDataType getType()

Gets the data type for a field, converting it to the more readable enum

Returns:

enum corresponding to the internal int value for the data type, or ItemDataType.TYPE_INVALID_OR_UNKNOWN if it is unknown

get

<T> T get(Class<T> valueType,
          T defaultValue)

Returns the item value converted to the specified data type.

We currently support the following value types out of the box:

• String
• Integer
• Long
• Double
• DominoDateTime
• LocalDate
• LocalTime
• OffsetDateTime
• TemporalAccessor (returned as DominoDateTime)

Additional value types are supported by implementing and registering DocumentValueConverter as Java services.

Type Parameters:

T - type of return value

Parameters:

valueType - class of return value

defaultValue - default value to be returned of object property is not set

Returns:

return value

Throws:

IllegalArgumentException - if the specified value type is unsupported

getAsList

<T> List<T> getAsList(Class<T> valueType,
                      List<T> defaultValue)

Returns a list of item values converted to the specified data type.

We currently support the following value types out of the box:

• String
• Integer
• Long
• Double
• DominoDateTime
• LocalDate
• LocalTime
• OffsetDateTime
• TemporalAccessor (returned as DominoDateTime)

Additional value types are supported by implementing and registering DocumentValueConverter as Java services.

Type Parameters:

T - type of return value

Parameters:

valueType - class of return value

defaultValue - default value to be returned of object property is not set

Returns:

value list

Throws:

IllegalArgumentException - if the specified value type is unsupported

getValue

List<Object> getValue()

Decodes the item value(s). The data is always returned as a list even though the list may contain only one element (e.g. for ItemDataType.TYPE_TEXT.
The following data types are currently supported:

• ItemDataType.TYPE_TEXT - List with String object
• ItemDataType.TYPE_TEXT_LIST - List of String objects
• ItemDataType.TYPE_NUMBER - List with Double object
• ItemDataType.TYPE_NUMBER_RANGE - List of Double objects
• ItemDataType.TYPE_TIME - List with Calendar object
• ItemDataType.TYPE_TIME_RANGE - List of Calendar objects
• ItemDataType.TYPE_OBJECT with the subtype Attachment (e.g. $File items) - List with Attachment object
• ItemDataType.TYPE_NOTEREF_LIST - List with one UNID
• ItemDataType.TYPE_UNAVAILABLE - returns an empty list

Returns:

a List of objects representing the item value

copyToDocument

void copyToDocument(Document doc,
                    boolean overwrite)

Copies this item to a new document, retaining the current name. TODO: If overwrite is false, does it create a duplicate item or abort?

Parameters:

doc - target document for the new item

overwrite - true to replace any existing item with the same name

copyToDocument

void copyToDocument(Document doc,
                    String newItemName,
                    boolean overwrite)

Copies this item to a new document, with a new Item name. TODO: If overwrite is false, does it create a duplicate item or abort?

Parameters:

doc - target document for the new item

newItemName - new Item name to save as

overwrite - true to replace any existing item with the same name

getSequenceNumber

int getSequenceNumber()

Incremental integer for the nth save this Item was last updated. Cross-reference with the $Revisions field for the date and time it was saved. Be aware that for very frequently updating documents, the integer will cycle back to 1

Returns:

integer corresponding to the nth time the document was saved

getFlags

Set<Item.ItemFlag> getFlags()

Gets all the field flags corresponding to the Item

Returns:

field flags applied, e.g. {SUMMARY,READERS}

isSummary

boolean isSummary()

Whether or not the SUMMARY field flag is applied on this Item. A document can only have a maximum 64Mb total SUMMARY field data Only SUMMARY items can be displayed in a View's column as a raw field value. Some data types, e.g. TYPE_MIME_PART, cannot be SUMMARY.

Returns:

true for SUMMARY Items

setSummary

void setSummary(boolean b)

Changes the summary field flag

Parameters:

b - new flag value

isNames

boolean isNames()

Whether or not the NAMES field flag is applied on this Item. NAMES fields are used to store Domino usernames and these fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Returns:

true for NAMES Items

isReaders

boolean isReaders()

Whether or not the READERS field flag is applied on this Item. READERS fields are used to store Domino usernames and restrict read access to documents. These fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Returns:

true for READERS Items

isReadWriters

boolean isReadWriters()

Whether or not the READWRITERS field flag is applied on this Item. READWRITERS fields are used to store Domino usernames and restrict saving changes to documents if the person only has Author access to the database. These fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Returns:

true for READWRITERS Items

isProtected

boolean isProtected()

Whether or not the Item prevents access if the person only has Author access to the database. If so, the developer will need to call setProtected(false) before making a change, and set it back to true afterwards. Item itm = doc.getFirstItem("Foo"); if (itm.isProtected()) { itm.setProtected(false); doc.replaceItemValue("Foo", "bar"); itm.setProtected(true); }

Returns:

true if editor access or above is required to edit the Item

isEncrypted

boolean isEncrypted()

Whether or not the Item requires additional encryption key in addition to database-level and document-level Reader access in order to see the content.

Returns:

true if the Item is encrypted

isSigned

boolean isSigned()

Whether or not the Item will be signed next time the document is saved. TODO: Under what circumstances would this be true and under what circumstances would it be false? i.e. Why shouldn't a developer just ignore this?

Returns:

true if the Item will be signed

setNames

void setNames(boolean isNames)

Sets the NAMES field flag on this Item. NAMES fields are used to store Domino usernames and these fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Parameters:

isNames - true to enable NAMES flag on the Item

setReaders

void setReaders(boolean isReaders)

Sets the READERS field flag on this Item. READERS fields are used to store Domino usernames and restrict read access to documents. These fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Parameters:

isReaders - true to enable READERS flag on the Item

setReadWriters

void setReadWriters(boolean isReadWriters)

Sets the READWRITERS field flag on this Item. READWRITERS fields are used to store Domino usernames and restrict saving changes to documents if the person only has Author access to the database. These fields can be checked by the server's Administration Process (adminp) to update if the username changes or the user is removed.

Parameters:

isReadWriters - true to enable READWRITERS flag on the Item

setProtected

void setProtected(boolean isProtected)

Change whether or not the Item prevents access if the person only has Author access to the database. If it is already protected and the current user has only Author access, the developer will need to call setProtected(false) before making a change, and set it back to true afterwards. Item itm = doc.getFirstItem("Foo"); if (itm.isProtected()) { itm.setProtected(false); doc.replaceItemValue("Foo", "bar"); itm.setProtected(true); }

Parameters:

isProtected - true if editor access or above is required to edit the Item

setEncrypted

void setEncrypted(boolean isEncrypted)

Change whether or not the Item requires additional encryption key in addition to database-level and document-level Reader access in order to see the content.

Parameters:

isEncrypted - true if the Item is encrypted

setSigned

void setSigned(boolean isSigned)

Change whether or not the Item will be signed next time the document is saved. TODO: Under what circumstances would this be true and under what circumstances would it be false? i.e. Why shouldn't a developer just ignore this?

Parameters:

isSigned - true if the Item will be signed

getProperties

DocumentProperties getProperties()

Extracts the key elements available in the Notes Client Document Properties window, so they can be made available in a serializable format

Returns:

a DocumentProperties object representing the document's meta properties

getMimeEntity

Optional<MimeEntity> getMimeEntity()

Retrieves the item content as a MIME entity, if this is a MIME item.

Returns:

an Optional describing a MimeEntity for the item content, or an empty one if this is not a MIME item

convertRFC822TextItem

Item convertRFC822TextItem()

This function converts the input ItemDataType.TYPE_RFC822_TEXT item in an open document to its pre-V5 equivalent; i.e. to ItemDataType.TYPE_TEXT, ItemDataType.TYPE_TEXT_LIST, or ItemDataType.TYPE_TIME.

For example, we convert the PostedDate ItemDataType.TYPE_RFC822_TEXT item to a ItemDataType.TYPE_TIME item.

It does not update the Domino database; to update the database, call Document.save().

Returns:

this item instance (for chaining)

remove

void remove()

Remove this item from the parent document

getValueLength

int getValueLength()

Returns the value length in bytes

Returns:

length