com.gentics.api.lib.datasource
Interface Datasource

All Superinterfaces:
java.lang.Cloneable
All Known Subinterfaces:
MultichannellingDatasource, VersioningDatasource, WritableMultichannellingDatasource, WriteableDatasource, WriteableVersioningDatasource
All Known Implementing Classes:
AbstractCacheableDatasource, AbstractDatasource, AbstractVersioningDatasource, ResolvableDatasource

public interface Datasource
extends java.lang.Cloneable

Interface for Datasources. Datasources can be configured to store/retrieve data in a generalized way.
Instances of this interface represent connections to the underlying storage system and are therefore not threadsafe.
This API might still change, and is intended and maintened for usage only. Don't implement your own datasources for now.
When the time comes, do not implement this interface directly, but extend the abstract class AbstractDatasource instead.


Nested Class Summary
static class Datasource.Sorting
          Inner class for definition of sorting
 
Field Summary
static int SORTORDER_ASC
          Constant for the sortorder "ASCENDING"
static int SORTORDER_DESC
          Constant for the sortorder "DESCENDING"
static int SORTORDER_NONE
          Constant for the sortorder "NONE" (ie.
 
Method Summary
 java.lang.Object clone()
          Clone the datasource (that means to create a copy that would work excactly like this datasource)
 DatasourceFilter createDatasourceFilter(Expression expression)
          Create a datasource filter for the given expression.
 int getCount()
          Deprecated. use getCount(DatasourceFilter) instead.
 int getCount(DatasourceFilter filter)
          Get the number of objects in the datasource that match the given filter
 int getCount(DatasourceFilter filter, java.util.Map<java.lang.String,java.lang.Object> specificParameters)
          Get the number of objects in the datasource that match the given filter
 int getCount2()
          Deprecated. use getCount(DatasourceFilter) instead.
 HandlePool getHandlePool()
          Get the handlepool used by this Datasource.
 java.lang.String getId()
          Returns the unique identifier for this Datasource.
 java.util.Collection getResult()
          Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.
 java.util.Collection<Resolvable> getResult(DatasourceFilter filter, java.lang.String[] prefillAttributes)
          Get the resolvables from the datasource that match the given datasource filter (unsorted).
 java.util.Collection<Resolvable> getResult(DatasourceFilter filter, java.lang.String[] prefillAttributes, int start, int count, Datasource.Sorting[] sortedColumns)
          Get the resolvables from the datasource that match the given datasource filter.
 java.util.Collection<Resolvable> getResult(DatasourceFilter filter, java.lang.String[] prefillAttributes, int start, int count, Datasource.Sorting[] sortedColumns, java.util.Map<java.lang.String,java.lang.Object> specificParameters)
          Get the resolvables from the datasource that match the given datasource filter.
 java.util.Collection getResult(int start, int count, java.lang.String sortBy, int sortOrder)
          Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.
 java.util.Collection getResult(int start, int count, java.lang.String sortBy, int sortOrder, java.util.Map specificParameters)
          Deprecated. use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.
 java.util.Collection getResult(java.lang.String sortBy, int sortOrder)
          Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.
 boolean hasChanged()
          Deprecated. deprecated since a datasource should be stateless, use hasChanged(long) instead.
 boolean hasChanged(long timestamp)
          Returns true when the data in the underlying storage layer might have changed since the given timestamp.
 boolean isValidAttribute(java.lang.String attributeName)
          Verifies that the given attribute name is valid and exists in the datasource.
 void setAttributeNames(java.lang.String[] names)
          Deprecated. Prefill Attributes can be given in getResult(DatasourceFilter, String[]) methods.
 void setRuleTree(RuleTree ruleTree)
          Deprecated. RuleTree is deprecated, use Expression and DatasourceFilter instead.
 

Field Detail

SORTORDER_NONE

static final int SORTORDER_NONE
Constant for the sortorder "NONE" (ie. order of returned row dependend on the underlying database and is most likely random.)

See Also:
Constant Field Values

SORTORDER_ASC

static final int SORTORDER_ASC
Constant for the sortorder "ASCENDING"

See Also:
Constant Field Values

SORTORDER_DESC

static final int SORTORDER_DESC
Constant for the sortorder "DESCENDING"

See Also:
Constant Field Values
Method Detail

setRuleTree

void setRuleTree(RuleTree ruleTree)
Deprecated. RuleTree is deprecated, use Expression and DatasourceFilter instead.

Set the RuleTree to be used as filter when data is retrieved from this datasource. The RuleTree may refer to attributes of the fetched objects by "object.[attribute]".
Example: setting the RuleTree object.name == "Username" will filter the Result to those objects from the datasource that have the attribute "name" set to "Username".

Parameters:
ruleTree - filter RuleTree
See Also:
getResult(DatasourceFilter, String[]), createDatasourceFilter(Expression)

setAttributeNames

void setAttributeNames(java.lang.String[] names)
Deprecated. Prefill Attributes can be given in getResult(DatasourceFilter, String[]) methods.

Defines Attribute to select or store.

Parameters:
names - array of attribute names

getResult

java.util.Collection getResult(int start,
                               int count,
                               java.lang.String sortBy,
                               int sortOrder)
                               throws DatasourceNotAvailableException
Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.

Returns data fetched from the Datasource using the given RuleTree as filter.

Parameters:
start - index of the first object to get after the filter and sorting have been applied (counting starts with 0)
count - maximum number of objects to return, -1 for no limit
sortBy - property to sortby, null for unsorted result. May also contain a comma separated list of attribute names
sortOrder - sort order, use one of SORTORDER_ASC, SORTORDER_DESC SORTORDER_NONE
Returns:
a Collection holding the retrieved objects
Throws:
DatasourceNotAvailableException

getResult

java.util.Collection getResult()
                               throws DatasourceNotAvailableException
Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.

Returns:
a Collection holding the retrieved objects
Throws:
DatasourceNotAvailableException

getResult

java.util.Collection getResult(java.lang.String sortBy,
                               int sortOrder)
                               throws DatasourceNotAvailableException
Deprecated. Use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.

Returns data fetched from the Datasource using the given RuleTree as filter.

Parameters:
sortBy - property to sortby, null for unsorted result. May also contain a comma separated list of attribute names
sortOrder - sort order, use one of SORTORDER_ASC, SORTORDER_DESC SORTORDER_NONE
Returns:
a Collection holding the retrieved objects
Throws:
DatasourceNotAvailableException

getResult

java.util.Collection getResult(int start,
                               int count,
                               java.lang.String sortBy,
                               int sortOrder,
                               java.util.Map specificParameters)
                               throws DatasourceNotAvailableException
Deprecated. use getResult(DatasourceFilter, String[]) methods with DatasourceFilter instead.

Returns data fetched from the Datasource using the given RuleTree as filter.

Parameters:
start - index of the first object to get after the filter and sorting have been applied (counting starts with 0)
count - maximum number of objects to return, -1 for no limit
sortBy - property to sortby, null for unsorted result. May also contain a comma separated list of attribute names
sortOrder - sort order, use one of SORTORDER_ASC, SORTORDER_DESC SORTORDER_NONE
specificParameters - map of specific parameters, which will be interpreted by some specific Datasources, may be null or empty (no specific parameters)
Returns:
a Collection holding the retrieved objects
Throws:
DatasourceNotAvailableException

getCount

int getCount()
Deprecated. use getCount(DatasourceFilter) instead.

Get the number of rows matching the given rule.

Returns:
# of rows in the datasource

getCount2

int getCount2()
              throws DatasourceNotAvailableException
Deprecated. use getCount(DatasourceFilter) instead.

Get the number of rows matching the given rule.

Returns:
# of rows in the datasource
Throws:
DatasourceNotAvailableException

getHandlePool

HandlePool getHandlePool()
Get the handlepool used by this Datasource. Internal method should not be invoked from outside.

Returns:
the handlepool

clone

java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Clone the datasource (that means to create a copy that would work excactly like this datasource)

Throws:
java.lang.CloneNotSupportedException

hasChanged

boolean hasChanged()
Deprecated. deprecated since a datasource should be stateless, use hasChanged(long) instead.

Return true when data in the underlying storage layer might have changed since the last invocation of getResult() (or any of it's variants). The specific implementations can simply return true when a change cannot be determined other than refetching the data or can do any specific checks for modified data.

Returns:
true when data might have changed, false if no data was changed (it is safe for the caller to reuse previously fetched data)

hasChanged

boolean hasChanged(long timestamp)
Returns true when the data in the underlying storage layer might have changed since the given timestamp.

Parameters:
timestamp - timestamp to check if data has propably changed - timestamp is a java timestamp - ie. milliseconds since 1970 like System.currentTimeMillis()
Returns:
true if data has changed since the given timestamp or if it is not impossible to determine if data was changed. - false if it is propably that data has not changed.

createDatasourceFilter

DatasourceFilter createDatasourceFilter(Expression expression)
                                        throws ExpressionParserException
Create a datasource filter for the given expression. The datasource filter can later be used to filter datasources of the same type.

Parameters:
expression - expression to transform into a datasource filter
Returns:
datasource filter
Throws:
ExpressionParserException - When the DatasourceFilter can't be created

getResult

java.util.Collection<Resolvable> getResult(DatasourceFilter filter,
                                           java.lang.String[] prefillAttributes)
                                           throws DatasourceException
Get the resolvables from the datasource that match the given datasource filter (unsorted).

Parameters:
filter - datasource filter
prefillAttributes - array of attribute names to prefill (null or empty for no prefilling)
Returns:
collection of resolvables matching the filter
Throws:
DatasourceException
See Also:
createDatasourceFilter(Expression)

getResult

java.util.Collection<Resolvable> getResult(DatasourceFilter filter,
                                           java.lang.String[] prefillAttributes,
                                           int start,
                                           int count,
                                           Datasource.Sorting[] sortedColumns)
                                           throws DatasourceException
Get the resolvables from the datasource that match the given datasource filter.

Parameters:
filter - datasource filter
prefillAttributes - array of attribute names to prefill (null or empty for no prefilling)
start - index of the first object to return
count - maximum number of objects to return (-1 for all objects).
sortedColumns - possible sorting (may be null for "no sorting")
Returns:
collection of resolvables matching the filter
Throws:
DatasourceException
See Also:
createDatasourceFilter(Expression)

getResult

java.util.Collection<Resolvable> getResult(DatasourceFilter filter,
                                           java.lang.String[] prefillAttributes,
                                           int start,
                                           int count,
                                           Datasource.Sorting[] sortedColumns,
                                           java.util.Map<java.lang.String,java.lang.Object> specificParameters)
                                           throws DatasourceException
Get the resolvables from the datasource that match the given datasource filter.

Parameters:
filter - datasource filter
prefillAttributes - array of attribute names to prefill (null or empty for no prefilling)
start - index of the first object to return
count - maximum number of objects to return (-1 for all objects).
sortedColumns - possible sorting (may be null for "no sorting")
specificParameters - map of specific parameters, which will be interpreted by some specific Datasources, may be null or empty (no specific parameters)
Returns:
collection of resolvables matching the filter
Throws:
DatasourceException
See Also:
createDatasourceFilter(Expression)

getCount

int getCount(DatasourceFilter filter)
             throws DatasourceException
Get the number of objects in the datasource that match the given filter

Parameters:
filter - datasource filter
Returns:
number of objects that match the filter
Throws:
DatasourceException
See Also:
createDatasourceFilter(Expression)

getCount

int getCount(DatasourceFilter filter,
             java.util.Map<java.lang.String,java.lang.Object> specificParameters)
             throws DatasourceException
Get the number of objects in the datasource that match the given filter

Parameters:
filter - datasource filter
specificParameters - map of specific parameters, which will be interpreted by some specific Datasources, may be null or empty (no specific parameters)
Returns:
number of objects that match the filter
Throws:
DatasourceException
See Also:
createDatasourceFilter(Expression)

getId

java.lang.String getId()
Returns the unique identifier for this Datasource.

Returns:
an unique identifier for this datasource.

isValidAttribute

boolean isValidAttribute(java.lang.String attributeName)
                         throws DatasourceException
Verifies that the given attribute name is valid and exists in the datasource. The use behind this is, that it is possible to verify that a query for a given attribute would succeed. Ie. if the DatasourceFilter implementation does not check for existing attributes this method may always return true.

Parameters:
attributeName - the attribute name to check
Returns:
true if the attribute is valid and exists, false otherwise.
Throws:
DatasourceException


Copyright © 2013 Gentics Software GmbH. All Rights Reserved.