Package com.im.df.api.capabilities
Class DFFieldPickListCapability
- java.lang.Object
-
- com.im.df.api.capabilities.DFFieldPickListCapability
-
- All Implemented Interfaces:
DFCapability
public final class DFFieldPickListCapability extends java.lang.Object implements DFCapability
This capability allows to specify a pick list values (dictionary) for the specific field. It is an extension ofDFField
. This list can be used during editing values, inserting new rows and querying the database. Pick list capability is expected to be used with Integer and Text fields. It doesn't have much meaning for field types like binary, etc.. There are several ways how pick list values can be provided. The chosen way is determined by setting theDFFieldPickListCapability.PickListType
. TheDFFieldPickListCapability.PickListType.NOT_USED
type means that the field supports a pick list, but the feature is currently switched off. For detailed description of other available types please seeDFFieldPickListCapability.PickListType
documentation.
This class also provides the list of values loading ability. To load all values of the selected type usegetAll()
. There are also a few related utility methods - for example for filtering values (filterActiveOrObsoleted(com.google.common.collect.ImmutableList, boolean)
orfilter(com.google.common.collect.ImmutableList, java.lang.String)
), loading existing the field values, parsing from text.
For the client code which doesn't need to configure thisDFFieldPickListCapability
settings, but only want to use it, it's necessary to call something like:DFField field = ... DFFieldPickListCapability picklist = DFFieldPickListCapability.getPickListIfUsed(field); ImmutableList<Item> values = picklist.getAll().get();
Of course this example is loading the values synchronously, which means it can be blocked for some time (if the values are loaded from web service or database for example). UseFuture
capabilities to prevent blocking call.
See also a utility method for obtainingDFFieldPickListCapability
fromDFField
:getPickListIfUsed(com.im.df.api.ddl.DFField)
- Since:
- 6.3
- Author:
- Petr Hamernik
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
DFFieldPickListCapability.FieldBridge
This is an interface playing role of a bridge between this capability and the field's implementation.static class
DFFieldPickListCapability.Item
Representation of a single value for the pick list.static class
DFFieldPickListCapability.PickListType
Type of how list is provided.
-
Field Summary
Fields Modifier and Type Field Description static int
CACHE_NEVER_EXPIRES
Cache never expires constant.static java.lang.String
DEFAULT_DELIM
Default delimiter for setting constant list as a single String.static java.lang.String
PROP_ADDING_NEW_VALUES_ALLOWED
static java.lang.String
PROP_CACHE_TIMEOUT
Property name forgetCacheTimeoutInSec()
andsetCacheTimeoutInSec(int, com.im.commons.progress.DFEnvironmentRW)
.static java.lang.String
PROP_CONSTANT_LIST
Property name forgetConstantList()
andsetConstantList(java.util.List, com.im.commons.progress.DFEnvironmentRW)
.static java.lang.String
PROP_LOADER_SCRIPT
Property name forgetLoaderScript()
andsetLoaderScript(java.lang.String, com.im.commons.progress.DFEnvironmentRW)
.static java.lang.String
PROP_PICK_LIST_VALUES
Property name for values.static java.lang.String
PROP_SELECTED_TYPE
Property name forgetSelectedType()
andsetSelectedType(PickListType, DFEnvironmentRW)
.static java.lang.String
SCRIPT_CLOSURE_NAME
The name of closure which is used in script loader to load the values.
-
Constructor Summary
Constructors Constructor Description DFFieldPickListCapability(DFField field, DFFieldPickListCapability.FieldBridge fieldBridge)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
clearCache(boolean stopTask)
DFFieldPickListCapability.Item
createItem(java.lang.Comparable<?> value)
Creates a newItem
from the value.DFFieldPickListCapability.Item
createItem(java.lang.Comparable<?> value, java.lang.String label)
Creates a newItem
from the value and its label.DFFieldPickListCapability.Item
createObsoletedItem(java.lang.Comparable<?> value, java.lang.String label)
Creates a newItem
from the value and its label.com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>
executeScript(java.lang.String loaderScript)
Executes the script given by parameter and returns values.static com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>
filter(com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> all, java.lang.String filter)
Filters list of items based on the specified substring.static com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>
filterActiveOrObsoleted(com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> all, boolean obsoleted)
Filters list of items based onDFFieldPickListCapability.Item.isObsoleted()
flag.com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>>
getAll()
Computes all values for currently selected type (seegetSelectedType()
).int
getCacheTimeoutInSec()
com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>
getConstantList()
DFField
getField()
java.lang.String
getListAsText(java.util.List<DFFieldPickListCapability.Item> values)
Converts list of values to plain text.java.lang.String
getLoaderScript()
static DFFieldPickListCapability
getPickListIfUsed(DFField field)
Gets aDFFieldPickListCapability
instance for aDFField
.DFFieldPickListCapability.PickListType
getSelectedType()
boolean
isAddingNewValuesAllowed()
com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>
loadExistingValuesForField()
Loads current existing values from field usingDFEntityDataProvider
.java.util.List<DFFieldPickListCapability.Item>
parseValuesFromText(java.lang.String valuesAsText)
Parses values from text.void
setAddingNewValuesAllowed(boolean addingNewValuesAllowed, com.im.commons.progress.DFEnvironmentRW env)
Specifies whether user is able to insert into database a new value, not just those provided by this pick list.void
setCacheTimeoutInSec(int cacheTimeoutInSec, com.im.commons.progress.DFEnvironmentRW env)
Sets timeout for the internal cache of the values (in seconds).void
setConstantList(java.util.List<DFFieldPickListCapability.Item> values, com.im.commons.progress.DFEnvironmentRW env)
Sets constant list of values.void
setLoaderScript(java.lang.String loaderScript, com.im.commons.progress.DFEnvironmentRW env)
Sets the groovy script list which should provides the list of values.void
setSelectedType(DFFieldPickListCapability.PickListType selectedType, com.im.commons.progress.DFEnvironmentRW env)
Sets the method how the list of values is provided.
-
-
-
Field Detail
-
PROP_SELECTED_TYPE
public static final java.lang.String PROP_SELECTED_TYPE
Property name forgetSelectedType()
andsetSelectedType(PickListType, DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
PROP_CONSTANT_LIST
public static final java.lang.String PROP_CONSTANT_LIST
Property name forgetConstantList()
andsetConstantList(java.util.List, com.im.commons.progress.DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
PROP_LOADER_SCRIPT
public static final java.lang.String PROP_LOADER_SCRIPT
Property name forgetLoaderScript()
andsetLoaderScript(java.lang.String, com.im.commons.progress.DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
PROP_CACHE_TIMEOUT
public static final java.lang.String PROP_CACHE_TIMEOUT
Property name forgetCacheTimeoutInSec()
andsetCacheTimeoutInSec(int, com.im.commons.progress.DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
PROP_ADDING_NEW_VALUES_ALLOWED
public static final java.lang.String PROP_ADDING_NEW_VALUES_ALLOWED
Property name forisAddingNewValuesAllowed()
andsetAddingNewValuesAllowed(boolean, com.im.commons.progress.DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
PROP_PICK_LIST_VALUES
public static final java.lang.String PROP_PICK_LIST_VALUES
Property name for values. PropertyChangeEvent with this property name is fired when values may change, but also in cases when cache is cleared. SeegetAll()
. The current implementation for this property change doesn't provide old and new value. These parameters arenull
. It's needed to call againgetAll()
when it's necessary.- See Also:
- Constant Field Values
-
CACHE_NEVER_EXPIRES
public static final int CACHE_NEVER_EXPIRES
Cache never expires constant. The value is zero.- See Also:
- Constant Field Values
-
SCRIPT_CLOSURE_NAME
public static final java.lang.String SCRIPT_CLOSURE_NAME
The name of closure which is used in script loader to load the values. The value isloadValues
. SeesetLoaderScript(java.lang.String, com.im.commons.progress.DFEnvironmentRW)
.- See Also:
- Constant Field Values
-
DEFAULT_DELIM
public static final java.lang.String DEFAULT_DELIM
Default delimiter for setting constant list as a single String. See alsoparseValuesFromText(java.lang.String)
.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
DFFieldPickListCapability
public DFFieldPickListCapability(DFField field, DFFieldPickListCapability.FieldBridge fieldBridge)
-
-
Method Detail
-
clearCache
public void clearCache(boolean stopTask)
-
getField
public DFField getField()
- Returns:
- The field associated with this instance of
DFFieldPickListCapability
.
-
getSelectedType
public DFFieldPickListCapability.PickListType getSelectedType()
- Returns:
- Currently selected type of pick list method.
-
setSelectedType
public void setSelectedType(DFFieldPickListCapability.PickListType selectedType, com.im.commons.progress.DFEnvironmentRW env)
Sets the method how the list of values is provided.- Parameters:
selectedType
- Newly selected typeenv
- The environment with DDL lock
-
getAll
public com.google.common.util.concurrent.ListenableFuture<com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item>> getAll()
Computes all values for currently selected type (seegetSelectedType()
). The method returnsListenableFuture
as the computation can take significant time. The values are either loaded (computed) or returned from cache. Cache is cleared after specified timeout and next time must be loaded again (seesetCacheTimeoutInSec(int, com.im.commons.progress.DFEnvironmentRW)
).- Returns:
ListenableFuture
providing list of all values
-
getConstantList
public com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> getConstantList()
- Returns:
- Current constant list of values. It returns list previously set by
setConstantList(java.util.List, com.im.commons.progress.DFEnvironmentRW)
even whengetSelectedType()
is currently different than the constant list type.
-
setConstantList
public void setConstantList(java.util.List<DFFieldPickListCapability.Item> values, com.im.commons.progress.DFEnvironmentRW env)
Sets constant list of values.- Parameters:
values
- New list of constant values.env
- The environment with DDL lock.
-
getLoaderScript
public java.lang.String getLoaderScript()
- Returns:
- The current groovy script of values provider. The script is persistent even when
getSelectedType()
is currently different than the script loader type. See alsosetLoaderScript(java.lang.String, com.im.commons.progress.DFEnvironmentRW)
.
-
setLoaderScript
public void setLoaderScript(java.lang.String loaderScript, com.im.commons.progress.DFEnvironmentRW env)
Sets the groovy script list which should provides the list of values. It is expected that the script has a closure with the nameSCRIPT_CLOSURE_NAME
(loadValues
).Closure has two parameters:
DFField
- the field of this pick list capabilityDFFieldPickListCapability
reference tothis
object - can be used for creating newItem
s usingcreateItem(java.lang.Comparable)
orcreateItem(java.lang.Comparable, java.lang.String)
orcreateObsoletedItem(java.lang.Comparable, java.lang.String)
.- Instance of
Item
which is just the value
It is expected that the closure returns a list of values. The script executor is pretty flexible and values can be provided in various formats. Each element can be one of these:
Comparable
which is just the valueList
with one or two values. The first is againComparable
and the second optional item isString
representing label of the item.- Instance of
Item
which is just the value
This is an example of script:
loadValues = { field, pickList -> return [ [1, "one"], [2, "two"], [3, "three"] ] }
For more examples see pick list script template in Instant JChem.- Parameters:
loaderScript
- The new version of loader script.env
- The environment with DDL lock.
-
getCacheTimeoutInSec
public int getCacheTimeoutInSec()
- Returns:
- Timeout for internal cache of the values (in seconds).
See
setCacheTimeoutInSec(int, com.im.commons.progress.DFEnvironmentRW)
for more details.
-
setCacheTimeoutInSec
public void setCacheTimeoutInSec(int cacheTimeoutInSec, com.im.commons.progress.DFEnvironmentRW env)
Sets timeout for the internal cache of the values (in seconds). The cache is used for values loaded either by loader script or from database. Cached values are discarded after this timeout and need to be loaded again. This feature is useful when pick list values can change frequently. Timeout zero means that cache never expires during one IJC schema session (seeCACHE_NEVER_EXPIRES
).- Parameters:
cacheTimeoutInSec
- New cache timeout [sec]env
- The environment with DDL lock.
-
isAddingNewValuesAllowed
public boolean isAddingNewValuesAllowed()
- Returns:
true
if user is allowed to insert new values to database when editing/inserting data.false
means that user can insert values only from the pick list. See alsosetAddingNewValuesAllowed(boolean, com.im.commons.progress.DFEnvironmentRW)
for more details.
-
setAddingNewValuesAllowed
public void setAddingNewValuesAllowed(boolean addingNewValuesAllowed, com.im.commons.progress.DFEnvironmentRW env)
Specifies whether user is able to insert into database a new value, not just those provided by this pick list. See alsoisAddingNewValuesAllowed()
for more details.- Parameters:
addingNewValuesAllowed
-true
means that users will be able to add also values undefined by pick-list in edit/insert data.env
- The environment with DDL lock.
-
executeScript
public com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> executeScript(java.lang.String loaderScript)
Executes the script given by parameter and returns values. For more info about the script seesetLoaderScript(java.lang.String, com.im.commons.progress.DFEnvironmentRW)
. This is just a utility method used byDFFieldPickListCapability
to execute script synchronously when script is set and this class is inDFFieldPickListCapability.PickListType.LOADER_SCRIPT
type. It is exposed as API method as it can be useful for script execution without setting it as current script.- Parameters:
loaderScript
- The script loader- Returns:
- The list of values
-
createItem
public DFFieldPickListCapability.Item createItem(java.lang.Comparable<?> value) throws java.lang.IllegalArgumentException
Creates a newItem
from the value. As label is not provided the item's label will be the value itself convertedtoString()
.- Parameters:
value
- The value to be wrapped into Item.- Returns:
- Newly created Item instance.
- Throws:
java.lang.IllegalArgumentException
- when value can't be converted using the field's convertor.
-
createItem
public DFFieldPickListCapability.Item createItem(java.lang.Comparable<?> value, java.lang.String label) throws java.lang.IllegalArgumentException
Creates a newItem
from the value and its label.- Parameters:
value
- The value to be wrapped into Item.label
- The label for the value.- Returns:
- Newly created Item instance.
- Throws:
java.lang.IllegalArgumentException
- when value can't be converted using the field's convertor.
-
createObsoletedItem
public DFFieldPickListCapability.Item createObsoletedItem(java.lang.Comparable<?> value, java.lang.String label) throws java.lang.IllegalArgumentException
Creates a newItem
from the value and its label. New Item will have an obsoleted flag switched on. SeeDFFieldPickListCapability.Item
for more details.- Parameters:
value
- The value to be wrapped into Item.label
- The label for the value.- Returns:
- Newly created Item instance.
- Throws:
java.lang.IllegalArgumentException
- when value can't be converted using the field's convertor.
-
loadExistingValuesForField
public com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> loadExistingValuesForField()
Loads current existing values from field usingDFEntityDataProvider
. This method always call DFEntityDataProvider and doesn't use cache of this object. Method is blocking and can take significant time especially when it's misused (for example for calculated fields on large table, or for large tables with many different values). This is just a utility method and doesn't modify internal state of thisDFFieldPickListCapability
even when it's switched toDFFieldPickListCapability.PickListType.FIELD_VALUES
type.- Returns:
- Values currently present in field - typically existing DB column values.
-
filter
public static com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> filter(com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> all, java.lang.String filter)
Filters list of items based on the specified substring. This search is case insensitive. The items are returned when eitherDFFieldPickListCapability.Item.getValue()
.toString() contains filter or whenDFFieldPickListCapability.Item.getLabel()
contains filter.- Parameters:
all
- All itemsfilter
- The searched string.- Returns:
- Only items which contains the filter as substring.
-
filterActiveOrObsoleted
public static com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> filterActiveOrObsoleted(com.google.common.collect.ImmutableList<DFFieldPickListCapability.Item> all, boolean obsoleted)
Filters list of items based onDFFieldPickListCapability.Item.isObsoleted()
flag.- Parameters:
all
- All itemsobsoleted
-true
to get only obsoleted items.false
to get only non-obsoleted items.- Returns:
- The filtered list.
-
getListAsText
public java.lang.String getListAsText(java.util.List<DFFieldPickListCapability.Item> values)
Converts list of values to plain text. Each item is written into a separate line. Label (if defined) is delimited with comma (DEFAULT_DELIM
). This is a reverse method toparseValuesFromText(java.lang.String)
.- Parameters:
values
- Values to be printed to String.- Returns:
- String representation of the list of items.
-
parseValuesFromText
public java.util.List<DFFieldPickListCapability.Item> parseValuesFromText(java.lang.String valuesAsText)
Parses values from text. Each element is expected in a separate line. Each line starts with the real value. If comma (DEFAULT_DELIM
) is present in the line the all text after the comma is used as a label (seeDFFieldPickListCapability.Item.getLabel()
). Empty lines (means line with only white spaces) are skipped. This is a reverse method togetListAsText(java.util.List)
.- Parameters:
valuesAsText
- Source text to be parsed.- Returns:
- List of items parsed from text.
-
getPickListIfUsed
public static DFFieldPickListCapability getPickListIfUsed(DFField field)
Gets aDFFieldPickListCapability
instance for aDFField
. This method may returnnull
if the field does not support pick lists or if the pick list is currently not used for the field.- Parameters:
field
- The field to get the pick list for.- Returns:
- An Instance of
DFFieldPickListCapability
for the given field, if the field supports pick lists andgetSelectedType()
is notDFFieldPickListCapability.PickListType.NOT_USED
. Returnsnull
if this capability is not present on the field or if it is set toNOT_USED
.
-
-