com.livescribe.afp
Class PropertyCollection

java.lang.Object
  com.livescribe.afp.PropertyCollection

public abstract class PropertyCollection
extends Object

This class manages a set of properties for a penlet. The properties are persisted in a file. The file name is either directly specified or chosen by the system using a given area ID.

It is a good idea to let this class handle the file contents to keep consistency in the future.

See Also:

Region.getAreaId()

Constructor Summary

PropertyCollection()

Method Summary

abstract boolean	addProperty(long propId, Object value) Adds a property to the collection.
abstract boolean	destroy() Destroys this property collection.
static boolean	exists(PenletContext context, String fileName) Tests if the specified property file exists.
static PropertyCollection	getInstance(PenletContext context, Region region) This is a factory method that returns an instance of the requested property collection.
static PropertyCollection	getInstance(PenletContext context, Region region, boolean createIfNotFound) This is a factory method that returns an instance of the requested property collection.
static PropertyCollection	getInstance(PenletContext context, String fileName) This is a factory method that returns an instance of the requested property collection.
static PropertyCollection	getInstance(PenletContext context, String fileName, boolean createIfNotFound) This is a factory method that returns an instance of the requested property collection.
abstract String	getProperty(long propId) Gets the value of the specified property.
abstract int	getPropertyCount() Gets the property count.
abstract int	removeProperties(int count) Deprecated.
abstract boolean	removeProperty(long propId) Removes the specified property.
abstract boolean	setProperty(long propId, Object value) Sets a property value.
abstract boolean	setProperty(long propId, Object value, boolean overwrite) Sets a property value.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PropertyCollection

public PropertyCollection()

Method Detail

getInstance

public static PropertyCollection getInstance(PenletContext context,
                                             String fileName,
                                             boolean createIfNotFound)

This is a factory method that returns an instance of the requested property collection. If the property file does not exist then it will be created if the createIfNotFound flag is set to true. If the file does not exist and createIfNotFound is set to false then this will return null.

It is common to use an ".xml" suffix for the files.

This will also return null if the file exists but is not valid.

Parameters:

context - the associated penlet context

fileName - the file to access

createIfNotFound - indicates whether to create the file if it is not found

Returns:

an instance of the requested property collection, or null on failure.

getInstance

public static PropertyCollection getInstance(PenletContext context,
                                             String fileName)

This is a factory method that returns an instance of the requested property collection. The property file will be created if it does not exist.

It is common to use an ".xml" suffix for the files.

This will return null if the file exists but is not valid.

Parameters:

context - the associated penlet context

fileName - the file to access

Returns:

an instance of the requested property collection, or null on failure.

getInstance

public static PropertyCollection getInstance(PenletContext context,
                                             Region region)

This is a factory method that returns an instance of the requested property collection. The property file will be created in a unique way by using the given area ID. The file will be created if it does not exist.

This will return null if the file exists but is not valid.

Parameters:

context - the associated penlet context

region - use the area ID from this Region

Returns:

an instance of the requested property collection, or null on failure.

See Also:

Region.getAreaId()

getInstance

public static PropertyCollection getInstance(PenletContext context,
                                             Region region,
                                             boolean createIfNotFound)

This is a factory method that returns an instance of the requested property collection. The property file will be created in a unique way by using the given area ID. If the file does not exist then this uses the createIfNotFound flag in the same way as getInstance(PenletContext, String, boolean).

This will return null if the file exists but is not valid.

Parameters:

context - the associated penlet context

region - use the area ID from this Region

Returns:

an instance of the requested property collection, or null on failure.

See Also:

Region.getAreaId()

exists

public static boolean exists(PenletContext context,
                             String fileName)

Tests if the specified property file exists.

Parameters:

context - the associated penlet context

fileName - the property file name

Returns:

true if the file exists and false otherwise.

addProperty

public abstract boolean addProperty(long propId,
                                    Object value)

Adds a property to the collection. If the property already exists then it will not be overwritten and this will return false.

The property value will be converted to a string via its Object.toString() method.

This will return false if the value is null or the collection has been destroyed.

Parameters:

propId - the 64-bit property ID

value - the property value, will be converted to a string

Returns:

whether the property was successfully added.

setProperty

public abstract boolean setProperty(long propId,
                                    Object value,
                                    boolean overwrite)

Sets a property value. If the value does not already exist then it will be created. If the property already exists then it will be overwritten only if overwrite is set to true.

This will return false if the value is null, the property was not modified, or if the collection has been destroyed.

Parameters:

propId - the 64-bit property ID

value - the new property value, will be converted to a string

overwrite - indicates whether an existing property should be overwritten

Returns:

whether the property was successfully modified.

setProperty

public abstract boolean setProperty(long propId,
                                    Object value)

Sets a property value. This will overwrite the property if it already exists.

This will return false if the value is null or the collection has been destroyed.

Parameters:

propId - the 64-bit property ID

value - the new property value

Returns:

whether the property was modified successfully.

See Also:

setProperty(long, Object, boolean)

removeProperty

public abstract boolean removeProperty(long propId)

Removes the specified property.

This will return false if the collection has been destroyed.

Parameters:

propId - the 64-bit property ID

Returns:

whether the property was successfully removed.

removeProperties

public abstract int removeProperties(int count)

Deprecated.

Removes a specified number of properties from this collection. If the specified number is greater than the proprety count then all properties will be removed and a count of zero will be returned.

This will return zero if the collection has been destroyed.

Parameters:

count - the number of properties to remove

Returns:

the remaining property count.

getProperty

public abstract String getProperty(long propId)

Gets the value of the specified property. If the property does not exist then this returns null.

This will return null if the collection has been destroyed.

Parameters:

propId - the 64-bit property ID

Returns:

the property value, or null if the property does not exist.

destroy

public abstract boolean destroy()

Destroys this property collection. This also removes the file from storage.

Returns:

whether the properties file was successfully removed.

getPropertyCount

public abstract int getPropertyCount()

Gets the property count. This will return zero if the count could not be accessed.

This will return zero if the collection has been destroyed.

Returns:

the property count, or zero on failure.