org.gcube.contentmanagement.layerindependent.descriptions
Class BasicStorageHints

java.lang.Object
  extended by org.gcube.contentmanagement.layerindependent.descriptions.BasicStorageHints

public class BasicStorageHints
extends java.lang.Object

Constants and implementation of set of Storage Hints.

Author:
michaelspringmann

Field Summary
static java.lang.String HINT
          generic hint String for error identification
static java.lang.String HINT_NAME_ACCESS_METHOD
          This hint is used to further specify a particular method of a protocol to use to access content.
static java.lang.String HINT_NAME_APPEND_CONTENT
          Defines whether the content should be appended to the preexisting content when storing at a location or existing content entirely replaced (which would be the default behaviour).
static java.lang.String HINT_NAME_APPEND_NAME_TO_LOCATION
          Defines that the name of an object should be appended to the given file location.
static java.lang.String HINT_NAME_APPEND_OID_TO_LOCATION
          Defines that the id of an object should be appended to the given file location.
static java.lang.String HINT_NAME_BYTES_TRANSFERRED
          Informs about how many bytes actually have been transferred
static java.lang.String HINT_NAME_CATALOG_FILE_NAME
          Used to return additional information about where a file has been stored, in particular when used together with a Grid file catalog like lfc.
static java.lang.String HINT_NAME_CONTENT_LOCATION
          Defines where files are located
static java.lang.String HINT_NAME_CONTENT_MIMETYPE
          Specifies a mime tpye like PROPERTY_VALUE_MIME_TYPE_* that should be stored as property PROPERTY_TYPE_MIME_TYPE after upload of content.
static java.lang.String HINT_NAME_DELEGATED_CREDENTIALS
          Defines the credentials that should be used, if applicable
static java.lang.String HINT_NAME_DELETE_AFTER_TRANSFER
          Defines after a file has been transfered, it should be deleted Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE
static java.lang.String HINT_NAME_DO_NOT_REGISTER_FILE_IN_CATALOG
          Defines that the transferred file should not be registered in the used file catalog, e.g.
static java.lang.String HINT_NAME_DO_NOT_UPDATE_CONTENT_MIMETYPE
          Specifies to not update the content mimetype.
static java.lang.String HINT_NAME_ELAPSED_TRANSFER_TIME
          Informs about how many milliseconds have been spent on the actual file transfer
static java.lang.String HINT_NAME_ERROR_MESSAGE
          This hint is used to give detailed report about a failure reusing the the existing hint API for signaling that an operation could not be executed as requested.
static java.lang.String HINT_NAME_GUESS_CONTENT_MIMETYPE
          Defines that, if possible, it is better to guess the content mimetype based on some appropriate approach instead of relying on the inforamtion given otherwise.
static java.lang.String HINT_NAME_IMPORT_VIRTUALLY
          Defines the password that should be used, if applicable Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE
static java.lang.String HINT_NAME_INITIATED_BY
          Defines the distinguished name that should be stored as the user that initiated some operation and therefore get stored as "created by" / "modified by"
static java.lang.String HINT_NAME_IS_LARGE_FILE
          Defines that the transferred file should be treated as a large file, in particular GFAL large file support should be used.
static java.lang.String HINT_NAME_LIMIT_CONTENT_LENGTH_READ
          Defines the maximal length of bytes to be transferred
static java.lang.String HINT_NAME_NEW_FILE_INSTEAD_OF_REPLACEMENT
          Defines that any existing file should not be overwritten with new content.
static java.lang.String HINT_NAME_OBJECT_ALREADY_VISITED
          Indicates that this object was visited before and to avoid both, unnecessary data transfer and endless loop, traversing stopped here Since value of hint has to be defined as well, if it is set, then the value HINT_VALUE_TRUE
static java.lang.String HINT_NAME_PASSWORD
          Defines the password that should be used, if applicable
static java.lang.String HINT_NAME_PREDEFINED_ID
          When a new object is created, this hint can be specified to make sure that it gets assigned a particular ID.
static java.lang.String HINT_NAME_PREFERRED_BUFFER_SIZE
          Defines the preferred buffer size that should be used, if possible.
static java.lang.String HINT_NAME_REACHED_MAX_RECURSION_DEPTH
          Defines that recursion stopped because maximum depth reached Since value of hint has to be defined as well, if it is set, then the value HINT_VALUE_TRUE
static java.lang.String HINT_NAME_READING_START_OFFSET
          Defines a positive number of bytes that should be skipped at the beginning of the file
static java.lang.String HINT_NAME_RETURN_NO_HINTS
          Defines that no hints should be returned Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}
static java.lang.String HINT_NAME_RETURN_OBJECT_WITHOUT_REFERENCES
          Defines that properties, but no referenced objects should be returned, can be combined with HINT_NAME_RETURN_NO_HINTS.
static java.lang.String HINT_NAME_RETURN_PLAIN_OBJECT
          Defines that no properties and no referenced objects should be returned, can be combined with HINT_NAME_RETURN_NO_HINTS.
static java.lang.String HINT_NAME_SMALL_FILES_IN_MESSAGE
          Defines that if a file is known to be smaller than some threshold, raw content will be returned by the server using inmessage:// instead of whatever has been defined as location to remove the overhead of reading them from disk, if they should not be stored permanently at the client, but processed by the client in memory anyway.
static java.lang.String HINT_NAME_SMALL_FILES_SIZE
          Defines the size in bytes of files, that should be considered small and therefore might be treated specifically.
static java.lang.String HINT_NAME_TRANSFER_CONTENT_IF_UPDATED_AFTER
          Defines that raw content should only be transfered, if there has been a update after some timestamp.
static java.lang.String HINT_NAME_USERNAME
          Defines the username that should be used, if applicable
static java.lang.String HINT_NAME_WARNING
          This hint is used to give a feedback if a situation occured, which is not by definition an error, but may have negative side-effects of which the user should be informed.
static java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_GET
          Indicates that HTTP request should be formulated as GET.
static java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_HEAD
          Indicates that HTTP request should be formulated as HEAD.
static java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_POST
          Indicates that HTTP request should be formulated as POST.
static java.lang.String HINT_VALUE_FALSE
          Constant to define a valid string to represent 'false'
static java.lang.String HINT_VALUE_TRUE
          Constant to define a valid string to represent 'true'
static BasicStorageHints NO_HINTS
          Deprecated. 
static java.lang.String VALUE_SEPARATOR
          In case the value of a hint consists of several individual parts that should easy to be programmatically split up again, this separator should be used to have an easy an consistent way to do so.
 
Constructor Summary
BasicStorageHints()
           
 
Method Summary
 void addConsumedHint(java.lang.String name, java.lang.String value)
          Adds a hint and immediately marks it as consumed.
 void addHint(java.lang.String name, java.lang.String value)
          Adds a new hint or replaces any existing one with the same name.
 void addWarning(java.lang.String message)
          Adds a human-readable warning to the hints.
 java.lang.String consumeHint(java.lang.String name, boolean onlyPreviouslyUnconsumed)
          Return the value for a hint and mark it immediately as consumed
 java.lang.String consumeHint(java.lang.String name, boolean onlyPreviouslyUnconsumed, java.lang.String defaultValue, boolean consumeDefault)
          Return the value for a hint and mark it immediately as consumed
 BasicStorageHints getConsumedHints()
          Returns a representation that contains all the hints (and only those hints), that have been flagged as consumed.
 java.util.Set getHintNames()
          Returns a set of all names of assigned hints
 java.lang.String getHintValue(java.lang.String name)
          Return the value for a hint
 java.lang.String getHintValue(java.lang.String name, java.lang.String defaultValue)
          Return the value for a hint
 BasicStorageHints getUnconsumedHints()
          Returns a representation that contains only those hints, that have not been flagged as consumed.
static java.lang.String[] getWarings(BasicStorageHints h)
          Returns an array of individual warnings instead of a single, long string containing all warnings.
 java.lang.String[] getWarnings()
          Returns an array of individual warnings instead of a single, long string containing all warnings.
 boolean hasConsumedHint(java.lang.String name)
          Returns whether a hint with a particular name has been assigned and has been consumed already
 boolean hasHint(java.lang.String name)
          Returns whether a hint with a particular name has been assigned
 boolean hasUnconsumedHint(java.lang.String name)
          Returns whether a hint with a particular name has been assigned and not yet consumed
 boolean isConsumedHint(java.lang.String name)
          Returns whether a hint has been flagged as consumed.
 int length()
          Returns the number of assigned hints
 boolean markHint(java.lang.String name, boolean consumed)
          Flags an hint as consumed or removes a flag
 java.lang.String removeHint(java.lang.String name)
          Removes a particular hint
static java.lang.String[] splitWarnings(java.lang.String concatinatedWarningMessages)
          Splits a potentially lng string containing several warnings into it's individual parts.
 java.lang.String toString()
          A human-readable representation as string of all hints
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

HINT

public static final java.lang.String HINT
generic hint String for error identification

See Also:
Constant Field Values

HINT_NAME_READING_START_OFFSET

public static final java.lang.String HINT_NAME_READING_START_OFFSET
Defines a positive number of bytes that should be skipped at the beginning of the file

See Also:
Constant Field Values

HINT_NAME_LIMIT_CONTENT_LENGTH_READ

public static final java.lang.String HINT_NAME_LIMIT_CONTENT_LENGTH_READ
Defines the maximal length of bytes to be transferred

See Also:
Constant Field Values

HINT_NAME_PREFERRED_BUFFER_SIZE

public static final java.lang.String HINT_NAME_PREFERRED_BUFFER_SIZE
Defines the preferred buffer size that should be used, if possible. This gives the opportunity, to let buffers match as good as possible accross system boundaries and therefore avoid situations, in which bufferes are only filled to a small portion causing more overhead. If the size is too big to be used in all affected systems, the system should reduce it idependently to something acceptable rather than failing.

See Also:
Constant Field Values

HINT_NAME_USERNAME

public static final java.lang.String HINT_NAME_USERNAME
Defines the username that should be used, if applicable

See Also:
Constant Field Values

HINT_NAME_PASSWORD

public static final java.lang.String HINT_NAME_PASSWORD
Defines the password that should be used, if applicable

See Also:
Constant Field Values

HINT_NAME_DELEGATED_CREDENTIALS

public static final java.lang.String HINT_NAME_DELEGATED_CREDENTIALS
Defines the credentials that should be used, if applicable

See Also:
Constant Field Values

HINT_NAME_INITIATED_BY

public static final java.lang.String HINT_NAME_INITIATED_BY
Defines the distinguished name that should be stored as the user that initiated some operation and therefore get stored as "created by" / "modified by"

See Also:
BasicPropertyDescription.PROPERTY_NAME_CREATED_BY, BasicPropertyDescription.PROPERTY_NAME_MODIFIED_BY, Constant Field Values

HINT_NAME_IMPORT_VIRTUALLY

public static final java.lang.String HINT_NAME_IMPORT_VIRTUALLY
Defines the password that should be used, if applicable Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_DELETE_AFTER_TRANSFER

public static final java.lang.String HINT_NAME_DELETE_AFTER_TRANSFER
Defines after a file has been transfered, it should be deleted Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_TRANSFER_CONTENT_IF_UPDATED_AFTER

public static final java.lang.String HINT_NAME_TRANSFER_CONTENT_IF_UPDATED_AFTER
Defines that raw content should only be transfered, if there has been a update after some timestamp. The time will be passed as time in milliseconds since 1.1.1970, so the value of the BasicPropertyDescription.PROPERTY_NAME_OBJECT_MODIFIED can be used directly. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
BasicPropertyDescription.PROPERTY_NAME_OBJECT_MODIFIED, BasicPropertyDescription.PROPERTY_TYPE_TIME_IN_MILLISECONDS, Constant Field Values

HINT_NAME_SMALL_FILES_IN_MESSAGE

public static final java.lang.String HINT_NAME_SMALL_FILES_IN_MESSAGE
Defines that if a file is known to be smaller than some threshold, raw content will be returned by the server using inmessage:// instead of whatever has been defined as location to remove the overhead of reading them from disk, if they should not be stored permanently at the client, but processed by the client in memory anyway. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
HINT_NAME_SMALL_FILES_SIZE, Constant Field Values

HINT_NAME_SMALL_FILES_SIZE

public static final java.lang.String HINT_NAME_SMALL_FILES_SIZE
Defines the size in bytes of files, that should be considered small and therefore might be treated specifically. This may affect system performance since inmessage transfer requires conversion to and from base64 encoding whenever the stubs are processed on server/client side, but on the other hand, avoids swithing to a different protocol for file transfer which may have again the communication overhead including authenticating again ... to read just a couple of bytes. Depending on how expensive the protocol switch is and how many layers are affected, the ideal number might vary. However, it cannot be increased over the AXIS limit for the size of the entire SOAP message, which leaves space for about 2 megabytes of raw content (size before base64 encoding).

See Also:
Constant Field Values

HINT_NAME_IS_LARGE_FILE

public static final java.lang.String HINT_NAME_IS_LARGE_FILE
Defines that the transferred file should be treated as a large file, in particular GFAL large file support should be used. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_DO_NOT_REGISTER_FILE_IN_CATALOG

public static final java.lang.String HINT_NAME_DO_NOT_REGISTER_FILE_IN_CATALOG
Defines that the transferred file should not be registered in the used file catalog, e.g. LFC Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
Constant Field Values

HINT_NAME_CATALOG_FILE_NAME

public static final java.lang.String HINT_NAME_CATALOG_FILE_NAME
Used to return additional information about where a file has been stored, in particular when used together with a Grid file catalog like lfc.

See Also:
Constant Field Values

HINT_NAME_APPEND_CONTENT

public static final java.lang.String HINT_NAME_APPEND_CONTENT
Defines whether the content should be appended to the preexisting content when storing at a location or existing content entirely replaced (which would be the default behaviour). This may not be supported by all content managers and therefore an error may occur

See Also:
Constant Field Values

HINT_NAME_APPEND_NAME_TO_LOCATION

public static final java.lang.String HINT_NAME_APPEND_NAME_TO_LOCATION
Defines that the name of an object should be appended to the given file location. Some characters may be replaced by underscore characters in order to ensure that the directory struture will not get messed up. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_APPEND_OID_TO_LOCATION

public static final java.lang.String HINT_NAME_APPEND_OID_TO_LOCATION
Defines that the id of an object should be appended to the given file location. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
Constant Field Values

HINT_NAME_NEW_FILE_INSTEAD_OF_REPLACEMENT

public static final java.lang.String HINT_NAME_NEW_FILE_INSTEAD_OF_REPLACEMENT
Defines that any existing file should not be overwritten with new content. Instead, a new filename will be generated and the new content will be stored there. The actual location where the file has been stored (because it is not the original one) must be returned as HINT_NAME_CONTENT_LOCATION. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
HINT_NAME_CONTENT_LOCATION, Constant Field Values

HINT_NAME_CONTENT_MIMETYPE

public static final java.lang.String HINT_NAME_CONTENT_MIMETYPE
Specifies a mime tpye like PROPERTY_VALUE_MIME_TYPE_* that should be stored as property PROPERTY_TYPE_MIME_TYPE after upload of content.

See Also:
BasicPropertyDescription.PROPERTY_TYPE_MIME_TYPE, Constant Field Values

HINT_NAME_DO_NOT_UPDATE_CONTENT_MIMETYPE

public static final java.lang.String HINT_NAME_DO_NOT_UPDATE_CONTENT_MIMETYPE
Specifies to not update the content mimetype.

See Also:
BasicPropertyDescription.PROPERTY_TYPE_MIME_TYPE, Constant Field Values

HINT_NAME_GUESS_CONTENT_MIMETYPE

public static final java.lang.String HINT_NAME_GUESS_CONTENT_MIMETYPE
Defines that, if possible, it is better to guess the content mimetype based on some appropriate approach instead of relying on the inforamtion given otherwise. E.g. if the content header of some URL for an HTTP is commonly false, it is better to guess the content type by analyzing the stream itself.

See Also:
HINT_NAME_CONTENT_MIMETYPE, Constant Field Values

HINT_NAME_CONTENT_LOCATION

public static final java.lang.String HINT_NAME_CONTENT_LOCATION
Defines where files are located

See Also:
Constant Field Values

HINT_NAME_BYTES_TRANSFERRED

public static final java.lang.String HINT_NAME_BYTES_TRANSFERRED
Informs about how many bytes actually have been transferred

See Also:
Constant Field Values

HINT_NAME_ELAPSED_TRANSFER_TIME

public static final java.lang.String HINT_NAME_ELAPSED_TRANSFER_TIME
Informs about how many milliseconds have been spent on the actual file transfer

See Also:
Constant Field Values

HINT_NAME_RETURN_NO_HINTS

public static final java.lang.String HINT_NAME_RETURN_NO_HINTS
Defines that no hints should be returned Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE}

See Also:
Constant Field Values

HINT_NAME_RETURN_PLAIN_OBJECT

public static final java.lang.String HINT_NAME_RETURN_PLAIN_OBJECT
Defines that no properties and no referenced objects should be returned, can be combined with HINT_NAME_RETURN_NO_HINTS. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
HINT_NAME_RETURN_NO_HINTS, Constant Field Values

HINT_NAME_RETURN_OBJECT_WITHOUT_REFERENCES

public static final java.lang.String HINT_NAME_RETURN_OBJECT_WITHOUT_REFERENCES
Defines that properties, but no referenced objects should be returned, can be combined with HINT_NAME_RETURN_NO_HINTS. Since value of hint has to be defined as well, this is normally set to HINT_VALUE_TRUE

See Also:
HINT_NAME_RETURN_NO_HINTS, Constant Field Values

HINT_NAME_REACHED_MAX_RECURSION_DEPTH

public static final java.lang.String HINT_NAME_REACHED_MAX_RECURSION_DEPTH
Defines that recursion stopped because maximum depth reached Since value of hint has to be defined as well, if it is set, then the value HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_OBJECT_ALREADY_VISITED

public static final java.lang.String HINT_NAME_OBJECT_ALREADY_VISITED
Indicates that this object was visited before and to avoid both, unnecessary data transfer and endless loop, traversing stopped here Since value of hint has to be defined as well, if it is set, then the value HINT_VALUE_TRUE

See Also:
Constant Field Values

HINT_NAME_PREDEFINED_ID

public static final java.lang.String HINT_NAME_PREDEFINED_ID
When a new object is created, this hint can be specified to make sure that it gets assigned a particular ID. This is needed, when the content is dumped and should be reinserted using again exactly the ID it had before. This should not harm / cause collision with system generated UUIDs, since one of there foundations is, that it is very unlikely to generate two times the same ID by accident. In case of a collision - e.g. an object with this ID exists already - this should be treated as an error and execution stops instead of probably overwriting valuable information.

See Also:
Constant Field Values

HINT_NAME_ERROR_MESSAGE

public static final java.lang.String HINT_NAME_ERROR_MESSAGE
This hint is used to give detailed report about a failure reusing the the existing hint API for signaling that an operation could not be executed as requested. This is used in particular used for bulk operations, when a list of results in homogenous items should be returned and execution should continue without throwing an exception as soon as an error occurs.

See Also:
HINT_NAME_WARNING, Constant Field Values

HINT_NAME_WARNING

public static final java.lang.String HINT_NAME_WARNING
This hint is used to give a feedback if a situation occured, which is not by definition an error, but may have negative side-effects of which the user should be informed. It therefore signals, that the operation was performed as requested, in contrast to HINT_NAME_ERROR_MESSAGE.

See Also:
HINT_NAME_ERROR_MESSAGE, Constant Field Values

HINT_NAME_ACCESS_METHOD

public static final java.lang.String HINT_NAME_ACCESS_METHOD
This hint is used to further specify a particular method of a protocol to use to access content.

See Also:
HINT_VALUE_ACCESS_METHOD_HTTP_GET, HINT_VALUE_ACCESS_METHOD_HTTP_POST, Constant Field Values

HINT_VALUE_ACCESS_METHOD_HTTP_GET

public static final java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_GET
Indicates that HTTP request should be formulated as GET. In case of any HTTP connection, this is the default, if no hint is specified. Other option might be HINT_VALUE_ACCESS_METHOD_HTTP_POST.

See Also:
HINT_NAME_ACCESS_METHOD, Constant Field Values

HINT_VALUE_ACCESS_METHOD_HTTP_POST

public static final java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_POST
Indicates that HTTP request should be formulated as POST.

See Also:
HINT_NAME_ACCESS_METHOD, Constant Field Values

HINT_VALUE_ACCESS_METHOD_HTTP_HEAD

public static final java.lang.String HINT_VALUE_ACCESS_METHOD_HTTP_HEAD
Indicates that HTTP request should be formulated as HEAD. This makes most sense only when internally used, e.g. to check if some location exists.

See Also:
HINT_NAME_ACCESS_METHOD, Constant Field Values

VALUE_SEPARATOR

public static final java.lang.String VALUE_SEPARATOR
In case the value of a hint consists of several individual parts that should easy to be programmatically split up again, this separator should be used to have an easy an consistent way to do so. It is defined in a way, that a simple String.split(String) should yield the individual parts again.

See Also:
Constant Field Values

HINT_VALUE_FALSE

public static final java.lang.String HINT_VALUE_FALSE
Constant to define a valid string to represent 'false'


HINT_VALUE_TRUE

public static final java.lang.String HINT_VALUE_TRUE
Constant to define a valid string to represent 'true'


NO_HINTS

@Deprecated
public static final BasicStorageHints NO_HINTS
Deprecated. 
Reusable instance for defining no hints

Constructor Detail

BasicStorageHints

public BasicStorageHints()
Method Detail

addHint

public void addHint(java.lang.String name,
                    java.lang.String value)
Adds a new hint or replaces any existing one with the same name.

Parameters:
name - the name of the hint
value - the value of the hint

addConsumedHint

public void addConsumedHint(java.lang.String name,
                            java.lang.String value)
Adds a hint and immediately marks it as consumed. This is convenient for hints, that are used for information only, so they will never be unconsumed. By using this method, a sequence of calls of addHint and markHint can be avoided.

Parameters:
name - the name of the hint
value - the value of the hint

getHintValue

public java.lang.String getHintValue(java.lang.String name)
Return the value for a hint

Parameters:
name - the name of the hint
Returns:
the value, if there is one for this hints; otherwise null

getHintValue

public java.lang.String getHintValue(java.lang.String name,
                                     java.lang.String defaultValue)
Return the value for a hint

Parameters:
name - the name of the hint
defaultValue - if value has not been set, this value will be return (instead of null)
Returns:
the value, if there is one for this hints; otherwise defaultValue

consumeHint

public java.lang.String consumeHint(java.lang.String name,
                                    boolean onlyPreviouslyUnconsumed)
Return the value for a hint and mark it immediately as consumed

Parameters:
name - the name of the hint
onlyPreviouslyUnconsumed - if set to true, only hints will get returned, which have not been marked as consumed yet. Instead, this will then also return null.
Returns:
the value, if there is one for this hints; otherwise null

consumeHint

public java.lang.String consumeHint(java.lang.String name,
                                    boolean onlyPreviouslyUnconsumed,
                                    java.lang.String defaultValue,
                                    boolean consumeDefault)
Return the value for a hint and mark it immediately as consumed

Parameters:
name - the name of the hint
onlyPreviouslyUnconsumed - if set to true, only hints will get returned, which have not been marked as consumed yet. Instead, this will then also return null.
defaultValue - if value has not been set, this value will be return (instead of null)
consumeDefault - if set to true, a new consumed hint will get created with the given name and default value
Returns:
the value, if there is one for this hints; otherwise defaultValue

getHintNames

public java.util.Set getHintNames()
Returns a set of all names of assigned hints

Returns:
the names of hints

removeHint

public java.lang.String removeHint(java.lang.String name)
Removes a particular hint

Parameters:
name - the name of the hint
Returns:
the value of the removed hint (if any); otherwise null

hasHint

public boolean hasHint(java.lang.String name)
Returns whether a hint with a particular name has been assigned

Parameters:
name - the name of the hint
Returns:
true, if such a hint has been assigned; false otherwise

hasUnconsumedHint

public boolean hasUnconsumedHint(java.lang.String name)
Returns whether a hint with a particular name has been assigned and not yet consumed

Parameters:
name - the name of the hint
Returns:
true, if such a hint has been assigned and not consumed; false otherwise

hasConsumedHint

public boolean hasConsumedHint(java.lang.String name)
Returns whether a hint with a particular name has been assigned and has been consumed already

Parameters:
name - the name of the hint
Returns:
true, if such a hint has been assigned and consumed; false otherwise

isConsumedHint

public boolean isConsumedHint(java.lang.String name)
Returns whether a hint has been flagged as consumed.

Parameters:
name - the name of the hint
Returns:
true, if flag has been set; false otherwise

markHint

public boolean markHint(java.lang.String name,
                        boolean consumed)
Flags an hint as consumed or removes a flag

Parameters:
name - name of the hint
consumed - true, if hint has been consumed; false otherwise
Returns:
true, if mark has been changed; false if no change was necessary

getConsumedHints

public BasicStorageHints getConsumedHints()
Returns a representation that contains all the hints (and only those hints), that have been flagged as consumed.

Returns:
all the consumed hints

getUnconsumedHints

public BasicStorageHints getUnconsumedHints()
Returns a representation that contains only those hints, that have not been flagged as consumed.

Returns:
all the unconsumed hints

length

public int length()
Returns the number of assigned hints

Returns:
the number of hints

toString

public java.lang.String toString()
A human-readable representation as string of all hints

Overrides:
toString in class java.lang.Object
Returns:
a string that can be used for debugging and logging

addWarning

public void addWarning(java.lang.String message)
Adds a human-readable warning to the hints. If other warnings already exist, the new message is contactinated using the VALUE_SEPARATOR.

Parameters:
message - the new warning message to add

splitWarnings

public static java.lang.String[] splitWarnings(java.lang.String concatinatedWarningMessages)
Splits a potentially lng string containing several warnings into it's individual parts. This method assumes, that the warnings have been concatinated used VALUE_SEPARATOR.

Parameters:
concatinatedWarningMessages - the message that might contain concatinated warnings
Returns:
an array with the individual warnings; or null, if the String was null

getWarings

public static java.lang.String[] getWarings(BasicStorageHints h)
Returns an array of individual warnings instead of a single, long string containing all warnings.

Parameters:
h - the hints to extract the warnings from
Returns:
an array with the individual warnings; or null, if there was no warning in the hints

getWarnings

public java.lang.String[] getWarnings()
Returns an array of individual warnings instead of a single, long string containing all warnings.

Returns:
an array with the individual warnings; or null, if there was no warning set for this object