org.nuxeo.ecm.directory

Interface Session

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

BaseSession, CoreDirectorySession, LDAPSession, MemoryDirectorySession, MongoDBSession, MultiDirectorySession, SQLSession

public interface Session
extends AutoCloseable

A session used to access entries in a directory.

This class is used to create, obtain, modify and delete entries in a directory.

Author:

glefter@nuxeo.com

See Also:

Directory.getSession()

Method Summary

Modifier and Type	Method and Description
boolean	authenticate(String username, String password) Checks that the credentials provided by the UserManager match those registered in the directory.
void	close() Closes the session and all open result sets obtained from this session.
DocumentModel	createEntry(DocumentModel entry) Creates an entry in a directory.
DocumentModel	createEntry(Map<String,Object> fieldMap) Creates an entry in a directory.
void	deleteEntry(DocumentModel docModel) Deletes a directory entry.
void	deleteEntry(String id) Deletes a directory entry by id.
void	deleteEntry(String id, Map<String,String> map) Deprecated. since 9.2 (unused), use deleteEntry(String) instead.
DocumentModelList	getEntries() Deprecated. since 6.0 Use query method instead with parameters
DocumentModel	getEntry(String id) Retrieves a directory entry using its id.
DocumentModel	getEntry(String id, boolean fetchReferences) Retrieves a directory entry using its id.
String	getIdField() The Id field is the name of the field that is used a primary key: unique and not null value in the whole directory.
String	getPasswordField()
List<String>	getProjection(Map<String,Serializable> filter, Set<String> fulltext, String columnName)
List<String>	getProjection(Map<String,Serializable> filter, String columnName) Executes a query using filter and return only the column columnName.
boolean	hasEntry(String id) Returns true if session has an entry with given id.
boolean	isAuthenticating() Tells whether the directory implementation can be used as an authenticating backend for the UserManager (based on login / password check).
boolean	isReadOnly()
DocumentModelList	query(Map<String,Serializable> filter) Executes a simple query.
DocumentModelList	query(Map<String,Serializable> filter, Set<String> fulltext) Executes a simple query.
DocumentModelList	query(Map<String,Serializable> filter, Set<String> fulltext, Map<String,String> orderBy) Executes a simple query.
DocumentModelList	query(Map<String,Serializable> filter, Set<String> fulltext, Map<String,String> orderBy, boolean fetchReferences) Executes a query with the possibility to fetch references
DocumentModelList	query(Map<String,Serializable> filter, Set<String> fulltext, Map<String,String> orderBy, boolean fetchReferences, int limit, int offset) Executes a query with the possibility to fetch a subset of the results.
void	setReadAllColumns(boolean readAllColumns) For test framework.
void	updateEntry(DocumentModel docModel) Updates a directory entry.

Method Detail

getEntry

DocumentModel getEntry(String id)
                throws DirectoryException

Retrieves a directory entry using its id.

TODO what happens when the entry is not found? return null if not found?

Parameters:

id - the entry id

Returns:

a DocumentModel representing the entry

Throws:

DirectoryException

getEntry

DocumentModel getEntry(String id,
                       boolean fetchReferences)
                throws DirectoryException

Retrieves a directory entry using its id.

Parameters:

id - the entry id

fetchReferences - boolean stating if references have to be fetched

Returns:

a DocumentModel representing the entry

Throws:

DirectoryException

getEntries

@Deprecated
DocumentModelList getEntries()
                                  throws DirectoryException

Deprecated. since 6.0 Use query method instead with parameters

Retrieves all the entries in the directory. If the remote server issues a size limit exceeded error while sending partial results up to that limit, the method DocumentModelList#totalsize on the returned list will return -2 as a special marker for truncated results.

Returns:

a collection with all the entries in the directory

Throws:

DirectoryException

SizeLimitExceededException - if the number of results is larger than the limit configured for the directory and the server does not send partial results.

createEntry

DocumentModel createEntry(Map<String,Object> fieldMap)
                   throws DirectoryException

Creates an entry in a directory.

Parameters:

fieldMap - A map with keys and values that should be stored in a directory

Note: The values in the map should be of type String

Returns:

The new entry created in the directory

Throws:

UnsupportedOperationException - if the directory does not allow the creation of new entries

DirectoryException - if a communication exception occurs or if an entry with the same id already exists.

updateEntry

void updateEntry(DocumentModel docModel)
          throws DirectoryException

Updates a directory entry.

Parameters:

docModel - The entry to update

Throws:

UnsupportedOperationException - if the directory does not support entry updating

DirectoryException - if a communication error occurs

deleteEntry

void deleteEntry(DocumentModel docModel)
          throws DirectoryException

Deletes a directory entry.

Parameters:

docModel - The entry to delete

Throws:

UnsupportedOperationException - if the directory does not support entry deleting

DirectoryException - if a communication error occurs

deleteEntry

void deleteEntry(String id)
          throws DirectoryException

Deletes a directory entry by id.

Parameters:

id - the id of the entry to delete

Throws:

UnsupportedOperationException - if the directory does not support entry deleting

DirectoryException - if a communication error occurs

deleteEntry

@Deprecated
void deleteEntry(String id,
                             Map<String,String> map)
                      throws DirectoryException

Deprecated. since 9.2 (unused), use deleteEntry(String) instead.

Deletes a directory entry by id and secondary ids.

This is used for hierarchical vocabularies, where the actual unique key is the couple (parent, id).

Parameters:

id - the id of the entry to delete.

map - a map of secondary key values.

Throws:

DirectoryException - if a communication error occurs.

query

DocumentModelList query(Map<String,Serializable> filter)
                 throws DirectoryException

Executes a simple query. The conditions will be 'AND'-ed. Search is done with exact match.

Does not fetch reference fields.

If the remote server issues a size limit exceeded error while sending partial results up to that limit, the method DocumentModelList#totalsize on the returned list will return -2 as a special marker for truncated results.

Parameters:

filter - a filter to apply to entries in directory

Returns:

a list of document models containing the entries matched by the query

Throws:

DirectoryException - if a communication error occurs

SizeLimitExceededException - if the number of results is larger than the limit configured for the directory and the server does not send partial results.

query

DocumentModelList query(Map<String,Serializable> filter,
                        Set<String> fulltext)
                 throws DirectoryException

Executes a simple query. The conditions will be 'AND'-ed.

fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.

If the remote server issues a size limit exceeded error while sending partial results up to that limit, the method DocumentModelList#totalsize on the returned list will return -2 as a special marker for truncated results.

Parameters:

filter - a filter to apply to entries in directory

fulltext - a set of field that should be treated as a fulltext search

Returns:

a list of document models containing the entries matched by the query

Throws:

DirectoryException - if a communication error occurs

SizeLimitExceededException - if the number of results is larger than the limit configured for the directory and the server does not send partial results.

query

DocumentModelList query(Map<String,Serializable> filter,
                        Set<String> fulltext,
                        Map<String,String> orderBy)
                 throws DirectoryException

Executes a simple query. The conditions will be 'AND'-ed and the result will be sorted by the orderBy criteria list.

fieldNames present in the fulltext set are treated as a fulltext match. Does not fetch reference fields.

If the remote server issues a size limit exceeded error while sending partial results up to that limit, the method DocumentModelList#totalsize on the returned list will return -2 as a special marker for truncated results.

Parameters:

filter - a filter to apply to entries in directory

orderBy - a LinkedHashMap with the 'order by' criterias.The key of an entry of this map represents the column name and the value of the same entry represent the column order,which may be 'asc' or 'desc'.

fulltext - a set of field that should be treated as a fulltext search

Returns:

a list of document models containing the entries matched by the query

Throws:

DirectoryException - if a communication error occurs

SizeLimitExceededException - if the number of results is larger than the limit configured for the directory and the server does not send partial results.

query

DocumentModelList query(Map<String,Serializable> filter,
                        Set<String> fulltext,
                        Map<String,String> orderBy,
                        boolean fetchReferences)
                 throws DirectoryException

Executes a query with the possibility to fetch references

Throws:

DirectoryException

See Also:

query(Map, Set, Map)

query

DocumentModelList query(Map<String,Serializable> filter,
                        Set<String> fulltext,
                        Map<String,String> orderBy,
                        boolean fetchReferences,
                        int limit,
                        int offset)
                 throws DirectoryException

Executes a query with the possibility to fetch a subset of the results. org.nuxeo.ecm.directory.BaseSession provides a default implementation fetching all results to return the subset. Not recommended.

Parameters:

limit - maximum number of results ignored if less than 1

offset - number of rows skipped before starting, will be 0 if less than 0.

Throws:

DirectoryException

Since:

5.7

See Also:

query(Map, Set, Map, boolean)

close

void close()
    throws DirectoryException

Closes the session and all open result sets obtained from this session.

Releases this Connection object's resources immediately instead of waiting for them to be automatically released.

TODO: should this operation auto-commit pending changes?

Specified by:

close in interface AutoCloseable

Throws:

DirectoryException - if a communication error occurs

getProjection

List<String> getProjection(Map<String,Serializable> filter,
                           String columnName)
                    throws DirectoryException

Executes a query using filter and return only the column columnName.

Parameters:

filter - the filter for the query

columnName - the column whose content should be returned

Returns:

the list with the values of columnName for the entries matching filter

Throws:

DirectoryException

SizeLimitExceededException - if the number of results is larger than the limit configured for the directory

getProjection

List<String> getProjection(Map<String,Serializable> filter,
                           Set<String> fulltext,
                           String columnName)
                    throws DirectoryException

Throws:

DirectoryException

isAuthenticating

boolean isAuthenticating()
                  throws DirectoryException

Tells whether the directory implementation can be used as an authenticating backend for the UserManager (based on login / password check).

Returns:

true is the directory is authentication aware

Throws:

DirectoryException

authenticate

boolean authenticate(String username,
                     String password)
              throws DirectoryException

Checks that the credentials provided by the UserManager match those registered in the directory. If username is not in the directory, this should return false instead of throrwing an exception.

Parameters:

username -

password -

Returns:

true is the credentials match those stored in the directory

Throws:

DirectoryException

getIdField

String getIdField()

The Id field is the name of the field that is used a primary key: unique and not null value in the whole directory. This field is also used as login field if the directory is authenticating.

Returns:

the name of the id field

getPasswordField

String getPasswordField()

Returns:

the name of the field to store the password if the directory is authenticating (can be null)

isReadOnly

boolean isReadOnly()

hasEntry

boolean hasEntry(String id)

Returns true if session has an entry with given id.

Since:

5.2M4

createEntry

DocumentModel createEntry(DocumentModel entry)

Creates an entry in a directory.

Parameters:

entry - the document model representing the entry to create

Returns:

The new entry created in the directory

Throws:

UnsupportedOperationException - if the directory does not allow the creation of new entries

DirectoryException - if a communication exception occurs or if an entry with the same id already exists.

Since:

5.2M4

setReadAllColumns

void setReadAllColumns(boolean readAllColumns)

For test framework. Changes the read/query methods to return all of the entries, including the password field.

Parameters:

readAllColumns - whether to read all columns

Since:

9.1