org.openmrs.customdatatype

Interface CustomDatatype<T>

Type Parameters:

T - the Java class used for typed values

All Known Implementing Classes:

BooleanDatatype, DateDatatype, FreeTextDatatype, LongFreeTextDatatype, RegexValidatedTextDatatype, SerializingCustomDatatype

public interface CustomDatatype<T>

Represents a custom datatype, which an administrator may use for global properties, attribute types, etc. Handles conversion between a typed Java object and a reference string which can be persisted in a database varchar column.

Since:

1.9

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	CustomDatatype.Summary A short reprepresentation of a custom value, along with an indication of whether this is the complete value, or just a summary.

Method Summary

Modifier and Type	Method and Description
T	fromReferenceString(java.lang.String referenceString) Converts a reference string to its typed value.
java.lang.String	getReferenceStringForValue(T typedValue) Gets the reference string that would be persisted for the given typed value.
CustomDatatype.Summary	getTextSummary(java.lang.String referenceString) Converts a reference string to a short (generally < 100 characters) plain-text representation of its value.
java.lang.String	save(T typedValue, java.lang.String existingValueReference) The OpenMRS service layer calls this method when a custom value of this datatype is saved (created or edited).
void	setConfiguration(java.lang.String config) A CustomValueDescriptor defines both a datatype and its configuration (e.g.
void	validate(T typedValue) Validates the given value to see if it is a legal value for the given handler.

Method Detail

setConfiguration

void setConfiguration(java.lang.String config)

A CustomValueDescriptor defines both a datatype and its configuration (e.g. a regex for a RegexValidatedString datatype). The framework will instantiate datatypes and call this method to set that configuration. Subclasses should define the format of this configuration.

Parameters:

config -

save

java.lang.String save(T typedValue,
                      java.lang.String existingValueReference)
               throws InvalidCustomValueException

The OpenMRS service layer calls this method when a custom value of this datatype is saved (created or edited). Implementations should persist the typed value, and return a valueReference that can be used to access that value in the future. (Simple datatype implementations that don't require external storage may just serialize their typedValue to a String and return that.) Implementations may safely assume that validate was called on typedValue before this method is called.

Parameters:

typedValue -

existingValueReference - If null, the custom value is being saved for the first time. If not null, this custom value has been saved before with the given reference. Implementations may choose to return the same value reference if they are overwriting the old value on remote storage.

Returns:

a valueReference that may be used in the future to retrieve typedValue

Throws:

InvalidCustomValueException

getReferenceStringForValue

java.lang.String getReferenceStringForValue(T typedValue)
                                     throws java.lang.UnsupportedOperationException

Gets the reference string that would be persisted for the given typed value. (This allows efficient searching for exact attribute values.)

Parameters:

typedValue -

Returns:

Throws:

java.lang.UnsupportedOperationException - if it is not feasible to calculate this efficiently (e.g. you'd need to go to remote storage)

fromReferenceString

T fromReferenceString(java.lang.String referenceString)
               throws InvalidCustomValueException

Converts a reference string to its typed value. This may be expensive, especially if the datatype needs to go to remote storage.

Parameters:

referenceString -

Returns:

the actual typed value for the given referenceString

Throws:

InvalidCustomValueException - if the persisted value is illegal (perhaps because datatype configuration was changed since this value was persisted)

getTextSummary

CustomDatatype.Summary getTextSummary(java.lang.String referenceString)

Converts a reference string to a short (generally < 100 characters) plain-text representation of its value. The return value also indicates whether this representation is a complete view of the value, or if there is more to display. Implementations of this method must be high-performance, e.g. if the method is called thousands of times for a table of objects with custom values.

Parameters:

referenceString -

Returns:

a summary representation of the given value

validate

void validate(T typedValue)
       throws InvalidCustomValueException

Validates the given value to see if it is a legal value for the given handler. (For example the RegexValidatedText type checks against a regular expression.)

Parameters:

typedValue -

Throws:

InvalidCustomValueException