org.fuin.utils4j
Class PropertiesFile

java.lang.Object
  org.fuin.utils4j.PropertiesFile

public class PropertiesFile
extends java.lang.Object

A properties file that is capable of merging concurrent changes made by another JVM or another process.

Constructor Summary

PropertiesFile(java.io.File file)
Constructor with file.

PropertiesFile(java.io.File file, java.lang.String encoding)
Constructor with file and encoding.

Method Summary

void	clear() Discards all properties in memory (not on disk!).
boolean	delete() Tries to delete the underlying file.
boolean	exists() Determines if the underlying file already exists.
java.lang.String	get(java.lang.String key) Returns a value for a given key.
java.lang.String	getEncoding() Returns the encoding of the file.
java.io.File	getFile() Returns the underlying file.
java.lang.String[]	getKeyArray() Returns an array of all known keys including the deleted ones.
java.util.List	getKeyList() Returns a list of all known keys including the deleted ones.
java.lang.String	getStatus(java.lang.String key) Returns a status text for a given key.
int	getTryLockMax() Returns the number of tries to lock before throwing an exception.
long	getTryWaitMillis() Returns the milliseconds to sleep between retries.
boolean	isLoaded() Returns if the underlying file has ever been read.
boolean	isRemoved(java.lang.String key) Returns if a property has been deleted.
java.util.Iterator	keyIterator() Returns a key iterator.
void	load() Loads or reloads the content of the underlying file.
void	put(java.lang.String key, java.lang.String value) Set a value for a property.
void	remove(java.lang.String key) Remove the property with the given key.
void	save(boolean sortByKey) Save the content from memory to disk.
void	save(java.lang.String[] comments, boolean sortByKey) Save the content from memory to disk.
void	save(java.lang.String comment, boolean sortByKey) Save the content from memory to disk.
void	setTryLockMax(int tryLockMax) Sets the number of tries to lock before throwing an exception.
void	setTryWaitMillis(long tryWaitMillis) Sets the milliseconds to sleep between retries.
int	size() Number of properties.
java.util.Properties	toProperties() Returns a copy of all properties.

Methods inherited from class java.lang.Object

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

Constructor Detail

PropertiesFile

public PropertiesFile(java.io.File file)

Constructor with file. Encoding is "UTF-8".

Parameters:

file - File reference.

PropertiesFile

public PropertiesFile(java.io.File file,
                      java.lang.String encoding)

Constructor with file and encoding.

Parameters:

file - File reference.

encoding - File encoding ("UTF-8" etc.)

Method Detail

getEncoding

public final java.lang.String getEncoding()

Returns the encoding of the file.

Returns:

File encoding ("UTF-8" etc.)

isLoaded

public final boolean isLoaded()

Returns if the underlying file has ever been read.

Returns:

If the file was loaded true else false.

clear

public final void clear()

Discards all properties in memory (not on disk!).

load

public final void load()
                throws java.io.IOException,
                       LockingFailedException,
                       MergeException

Loads or reloads the content of the underlying file. Current properties in memory will NOT be discarded! If you want to discard the current values you must call clear() before!

Throws:

java.io.IOException - Error reading the file.

LockingFailedException - Locking the file failed.

MergeException - A problem occurred when merging the properties in memory and from disk.

save

public final void save(boolean sortByKey)
                throws java.io.IOException,
                       MergeException,
                       LockingFailedException

Save the content from memory to disk.

Parameters:

sortByKey - Sort the properties by key before saving?

Throws:

java.io.IOException - Error writing the file.

MergeException - One or more properties were modified concurrently.

LockingFailedException - Locking the file failed.

save

public final void save(java.lang.String comment,
                       boolean sortByKey)
                throws java.io.IOException,
                       MergeException,
                       LockingFailedException

Save the content from memory to disk.

Parameters:

comment - Comment to prepend (Should not include the "#" comment sign - It will be prepended automatically).

sortByKey - Sort the properties by key before saving?

Throws:

java.io.IOException - Error writing the file.

MergeException - One or more properties were modified concurrently.

LockingFailedException - Locking the file failed.

save

public final void save(java.lang.String[] comments,
                       boolean sortByKey)
                throws java.io.IOException,
                       MergeException,
                       LockingFailedException

Save the content from memory to disk.

Parameters:

comments - Comments to prepend (Should not include the "#" comment sign - It will be prepended automatically).

sortByKey - Sort the properties by key before saving?

Throws:

java.io.IOException - Error writing the file.

MergeException - One or more properties were modified concurrently.

LockingFailedException - Locking the file failed.

get

public final java.lang.String get(java.lang.String key)

Returns a value for a given key.

Parameters:

key - Key to find.

Returns:

Value or null if the key is unknown.

getStatus

public final java.lang.String getStatus(java.lang.String key)

Returns a status text for a given key.

Parameters:

key - Key to find.

Returns:

Status text or null if the key is unknown.

put

public final void put(java.lang.String key,
                      java.lang.String value)

Set a value for a property. If a property with the key is already known the value will be changed. Otherwise a new property will be created.

Parameters:

key - Key to set.

value - Value to set.

remove

public final void remove(java.lang.String key)

Remove the property with the given key. The internal property object is not deleted itself but it's value is set to null and the method isDeleted() will return true.

Parameters:

key - Key for the property to remove.

isRemoved

public final boolean isRemoved(java.lang.String key)

Returns if a property has been deleted.

Parameters:

key - Key for the property to check.

Returns:

If the property is unknown or has been deleted true else false.

size

public final int size()

Number of properties.

Returns:

All known properties including deleted ones.

getFile

public final java.io.File getFile()

Returns the underlying file.

Returns:

Properties file reference.

getKeyList

public final java.util.List getKeyList()

Returns a list of all known keys including the deleted ones.

Returns:

List of keys.

getKeyArray

public final java.lang.String[] getKeyArray()

Returns an array of all known keys including the deleted ones.

Returns:

Array of keys.

keyIterator

public final java.util.Iterator keyIterator()

Returns a key iterator.

Returns:

Iterates over all keys including the deleted ones.

toProperties

public final java.util.Properties toProperties()

Returns a copy of all properties.

Returns:

All key/values without deleted ones.

getTryLockMax

public final int getTryLockMax()

Returns the number of tries to lock before throwing an exception.

Returns:

Number of tries (default=3).

setTryLockMax

public final void setTryLockMax(int tryLockMax)

Sets the number of tries to lock before throwing an exception.

Parameters:

tryLockMax - Number of tries (default=3).

getTryWaitMillis

public final long getTryWaitMillis()

Returns the milliseconds to sleep between retries.

Returns:

Milliseconds.

setTryWaitMillis

public final void setTryWaitMillis(long tryWaitMillis)

Sets the milliseconds to sleep between retries.

Parameters:

tryWaitMillis - Milliseconds.

exists

public final boolean exists()

Determines if the underlying file already exists.

Returns:

If the file exists true else false

delete

public final boolean delete()

Tries to delete the underlying file. The properties in memory remain unchanged. If you want also to remove the properties in memory call clear().

Returns:

If the files was deleted true else false