com.marklogic.client.pojo

Interface PojoRepository<T,ID extends java.io.Serializable>

public interface PojoRepository<T,ID extends java.io.Serializable>

PojoRepository is the central class for the Pojo Facade. It supports CRUD operations and search. Each PojoRepository instance operates on only one pojo class. Create new PojoRepository instances based on your custom pojo type like so:

    public class MyClass {
        @Id
        public Integer getMyId() {
            ...
        }
        public void setMyId(Integer integer) {
            ...
        }
        ...
    }
    ...
    DatabaseClient client = ...;
    PojoRepository<MyClass, Integer> myClassRepo =
        client.newPojoRepository(MyClass.class, Integer.class);

Where MyClass is your custom pojo type, and myId is the bean property of type Integer marked with the @Id annotation. The @Id annotation can be attached to a public field or a public getter or a public setter. The bean property marked with @Id must be a native type or Serializable class and must contain an identifier value unique across all persisted instances of that type or the instance will overwrite the persisted instance with the same identifier.

The current implementation of the Pojo Facade uses Jackson databind for serialization and deserialization to and from json. Thus only classes which can be serialized and deserialized directly by Jackson can be serialized by the Pojo Facade. Every bean property including the one marked with @Id must either expose a public field or both a public getter and a public setter. To test if your class can be directly serialized and deserialized by Jackson, perform the following:

    ObjectMapper objectMapper = new ObjectMapper();
    String value = objectMapper.writeValueAsString(myObjectIn);
    MyClass myObjectOut = objectMapper.readValue(value, MyClass.class);

If that works but the configured objectMapper in the Pojo Facade is different and not working, you can troubleshoot by directly accessing the objectMapper used by the Pojo Facade using an unsupported internal method attached to the current implementation: com.marklogic.client.impl.PojoRepositoryImpl.

    ObjectMapper objectMapper = ((PojoRepositoryImpl) myClassRepo).getObjectMapper();

Special handling is provided for bean properties of type Date and Calendar. The current implementation of Jackson ObjectMapper changes the timezone to UTC. The serialized format is ISO 8601 format which is compatible with xs:dateTime format and can therefore be indexed in the server by a path range index of type dateTime. However, if you wish to query using a range index, it is recommended that you modify serialization to remove the class wrapper by adding a JsonTypeInfo annotation like so:

    @JsonTypeInfo(use=JsonTypeInfo.Id.NONE, include=JsonTypeInfo.As.EXTERNAL_PROPERTY)
    public Calendar getMyDateTime();

That way you can query the field directly without needing to traverse the java.util.GregorianCalendar type wrapper. By removing that wrapper, you can create a query like this:

    PojoQueryBuilder qb = pojoRepository.getQueryBuilder();
    PojoQueryDefinition query = qb.range("myDateTime", Operator.LT, Calendar.getInstance());

If your class has properties which are classes (non-native types) they will be automatically serialized and deserialized, but can only be written, read, or searched as properties of the parent instance. If you wish to directly write, read, or search instances of another class, create and use an instance of PojoRepository specific to that class.

Since PojoRepository stores in JSON format, which limits number precision to 15 significant digits (IEEE754 double precision), you will lose precision on numbers longer than 15 significant digits. If you desire larger numbers with no loss of precision, use Strings to persist those numbers.

Method Summary

Modifier and Type	Method and Description
long	count() The number of documents of the type managed by this PojoRepository persisted in the database
long	count(PojoQueryDefinition query) The number of documents of the type managed by this PojoRepository persisted in the database which match the query
long	count(PojoQueryDefinition query, Transaction transaction) In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database which match the query
long	count(java.lang.String... collections) The number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections
long	count(java.lang.String[] collections, Transaction transaction) In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections
long	count(Transaction transaction) In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database
void	delete(ID... ids) Deletes from the database the persisted pojo instances with the corresponding ids
void	delete(ID[] ids, Transaction transaction) As part of transaction, deletes from the database the documents with the corresponding ids
void	deleteAll() Deletes from the database all documents of the type managed by this PojoRepositoryof type T persisted by the pojo facade
void	deleteAll(Transaction transaction) As part of transaction, deletes from the database all documents of the type managed by this PojoRepositoryof type T persisted by the pojo facade
boolean	exists(ID id) True if a document exists in the database with the specified id
boolean	exists(ID id, Transaction transaction) True if in the context of transaction, a document exists in the database with the specified id
java.lang.String	getDocumentUri(T pojo)
ID	getId(T entity) Get the value of the id field (the field marked with the @Id annotation).
long	getPageLength() The number of instances per page returned when calling readAll or search (Default: 50).
PojoQueryBuilder<T>	getQueryBuilder() Get a PojoQueryBuilder for the type managed by this PojoRepository.
T	read(ID id) Read one persisted pojo by id and unmarshall its data into a new pojo instance.
PojoPage<T>	read(ID[] ids) Read multiple persisted pojos by id and unmarshall their data into new pojo instances.
PojoPage<T>	read(ID[] ids, Transaction transaction) Within an open transaction, read multiple persisted pojos and unmarshall their data into new pojo instances.
T	read(ID id, Transaction transaction) Within an open transaction, read one persisted pojo by id and unmarshall its data into a new pojo instance.
PojoPage<T>	readAll(long start) Read one page of persisted pojos of the type managed by this PojoRepository and unmarshall their data into new pojo instances.
PojoPage<T>	readAll(long start, Transaction transaction) Within an open transaction, read one page of persisted pojos of the type managed by this PojoRepository and unmarshall their data into new pojo instances.
PojoPage<T>	search(long start, java.lang.String... collections) Find all persisted pojos of the type managed by this PojoRepository also in one of the specified collections and unmarshall their data into new pojo instances.
PojoPage<T>	search(long start, Transaction transaction, java.lang.String... collections) Within an open transaction, find all persisted pojos of the type managed by this PojoRepository also in one of the specified collections and unmarshall their data into new pojo instances.
PojoPage<T>	search(PojoQueryDefinition query, long start) Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances.
PojoPage<T>	search(PojoQueryDefinition query, long start, SearchReadHandle searchHandle)
PojoPage<T>	search(PojoQueryDefinition query, long start, SearchReadHandle searchHandle, Transaction transaction) Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances.
PojoPage<T>	search(PojoQueryDefinition query, long start, Transaction transaction) Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances.
void	setPageLength(long length) Set the number of instances per page returned when calling readAll or search.
void	write(T entity) Write this instance to the database.
void	write(T entity, java.lang.String... collections) Does everything in write(T) but also adds your collections to the persisted instance.
void	write(T entity, Transaction transaction) Does everything in write(T) but in your multi-statement transaction context.
void	write(T entity, Transaction transaction, java.lang.String... collections) Does everything in write(T) but also adds your collections to the persisted instance and performs the write in your multi-statement transaction context.

Method Detail

getId

ID getId(T entity)

Get the value of the id field (the field marked with the @Id annotation).

Parameters:

entity - the entity instance from which you want to get the id value

Returns:

the id value for this entity of type ID

write

void write(T entity)
    throws ResourceNotFoundException,
           ForbiddenUserException,
           FailedRequestException

Write this instance to the database. Uses the field marked with @Id annotation to generate a unique uri for the document. Adds a collection with the fully qualified class name. Uses a particular configuration of ObjectMapper to generate the serialized JSON format.

Parameters:

entity - your pojo instance of the type managed by this PojoRepository

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

write

void write(T entity,
           java.lang.String... collections)
    throws ResourceNotFoundException,
           ForbiddenUserException,
           FailedRequestException

Does everything in write(T) but also adds your collections to the persisted instance.

Parameters:

entity - your pojo instance of the type managed by this PojoRepository

collections - the collections to add to this instance in the database

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

write

void write(T entity,
           Transaction transaction)
    throws ResourceNotFoundException,
           ForbiddenUserException,
           FailedRequestException

Does everything in write(T) but in your multi-statement transaction context.

Parameters:

entity - your pojo instance of the type managed by this PojoRepository

transaction - the open transaction in which to write this instance

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

write

void write(T entity,
           Transaction transaction,
           java.lang.String... collections)
    throws ResourceNotFoundException,
           ForbiddenUserException,
           FailedRequestException

Does everything in write(T) but also adds your collections to the persisted instance and performs the write in your multi-statement transaction context. .

Parameters:

entity - your pojo instance of the type managed by this PojoRepository

transaction - the open transaction in which to write this instance

collections - the collections to add to this instance in the database

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

exists

boolean exists(ID id)
        throws ForbiddenUserException,
               FailedRequestException

True if a document exists in the database with the specified id

Parameters:

id - the unique identifier of the pojo (the value of the field annotated with @Id)

Returns:

true if a document exists in the database with the specified id

Throws:

ForbiddenUserException

FailedRequestException

exists

boolean exists(ID id,
               Transaction transaction)
        throws ForbiddenUserException,
               FailedRequestException

True if in the context of transaction, a document exists in the database with the specified id

Parameters:

id - the unique identifier of the pojo (the value of the field annotated with @Id)

transaction - the transaction in which this exists check is participating (Will open a read lock on the document. The read lock is released when the transaction is committed or rolled back.)

Returns:

true if in the context of transaction, a document exists in the database with the specified id

Throws:

ForbiddenUserException

FailedRequestException

count

long count()
    throws ForbiddenUserException,
           FailedRequestException

The number of documents of the type managed by this PojoRepository persisted in the database

Returns:

The number of documents of the type managed by this PojoRepository persisted in the database

Throws:

ForbiddenUserException

FailedRequestException

count

long count(Transaction transaction)
    throws ForbiddenUserException,
           FailedRequestException

In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database

Parameters:

transaction - the transaction in which this count is participating (Will open a read lock on all matched documents. The read lock is released when the transaction is committed or rolled back.)

Returns:

in the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database

Throws:

ForbiddenUserException

FailedRequestException

count

long count(java.lang.String... collections)
    throws ForbiddenUserException,
           FailedRequestException

The number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections

Parameters:

collections - matches must belong to at least one of the specified collections

Returns:

the number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections

Throws:

ForbiddenUserException

FailedRequestException

count

long count(java.lang.String[] collections,
           Transaction transaction)
    throws ForbiddenUserException,
           FailedRequestException

In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections

Parameters:

collections - matches must belong to at least one of the specified collections

transaction - the transaction in which this count is participating (Will open a read lock on all matched documents. The read lock is released when the transaction is committed or rolled back.)

Returns:

in the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database with at least one of the criteria collections

Throws:

ForbiddenUserException

FailedRequestException

count

long count(PojoQueryDefinition query)
    throws ForbiddenUserException,
           FailedRequestException

The number of documents of the type managed by this PojoRepository persisted in the database which match the query

Parameters:

query - the query to perform to determine the number of matching instance in the db

Returns:

the number of instance in the db matching the query

Throws:

ForbiddenUserException

FailedRequestException

count

long count(PojoQueryDefinition query,
           Transaction transaction)
    throws ForbiddenUserException,
           FailedRequestException

In the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database which match the query

Parameters:

query - the query which results much match (queries are run unfiltered by default)

transaction - the transaction in which this count is participating (Will open a read lock on all matched documents. The read lock is released when the transaction is committed or rolled back.)

Returns:

in the context of transaction, the number of documents of the type managed by this PojoRepository persisted in the database which match the query

Throws:

ForbiddenUserException

FailedRequestException

delete

void delete(ID... ids)
     throws ResourceNotFoundException,
            ForbiddenUserException,
            FailedRequestException

Deletes from the database the persisted pojo instances with the corresponding ids

Parameters:

ids - the ids for the pojo instances to delete from the server

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

delete

void delete(ID[] ids,
            Transaction transaction)
     throws ResourceNotFoundException,
            ForbiddenUserException,
            FailedRequestException

As part of transaction, deletes from the database the documents with the corresponding ids

Parameters:

ids - the ids of instances to delete

transaction - the transaction within which to perform the delete

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

deleteAll

void deleteAll()
        throws ResourceNotFoundException,
               ForbiddenUserException,
               FailedRequestException

Deletes from the database all documents of the type managed by this PojoRepositoryof type T persisted by the pojo facade

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

deleteAll

void deleteAll(Transaction transaction)
        throws ResourceNotFoundException,
               ForbiddenUserException,
               FailedRequestException

As part of transaction, deletes from the database all documents of the type managed by this PojoRepositoryof type T persisted by the pojo facade

Parameters:

transaction - the transaction within which to perform the delete

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

read

T read(ID id)
throws ResourceNotFoundException,
       ForbiddenUserException,
       FailedRequestException

Read one persisted pojo by id and unmarshall its data into a new pojo instance.

Parameters:

id - the unique identifier of the pojo (the value of the field annotated with @Id)

Returns:

an instance of the correct type populated with the persisted data from the database

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

read

T read(ID id,
       Transaction transaction)
throws ResourceNotFoundException,
       ForbiddenUserException,
       FailedRequestException

Within an open transaction, read one persisted pojo by id and unmarshall its data into a new pojo instance.

Parameters:

id - the unique identifier of the pojo (the value of the field annotated with @Id)

transaction - the transaction in which this read is participating (will open a read lock on each document matched that is released when the transaction is committed or rolled back)

Returns:

an instance of the correct type populated with the persisted data from the database

Throws:

ResourceNotFoundException

ForbiddenUserException

FailedRequestException

read

PojoPage<T> read(ID[] ids)
          throws ForbiddenUserException,
                 FailedRequestException

Read multiple persisted pojos by id and unmarshall their data into new pojo instances. If at least one instance is found but others are not, ignores the instances not found. While this returns a PojoPage, the PageSize will match the number of instances found, and will ignore getPageLength(). To paginate, send a smaller set of ids at a time.

Parameters:

ids - the unique identifiers of the pojos (the values of the field annotated with @Id)

Returns:

a set of instances of the correct type populated with the persisted data. Since this call produces a finite set, only one page is returned and therefore PojoPage pagination methods will not be helpful as they would be from calls to search.

Throws:

ForbiddenUserException

FailedRequestException

read

PojoPage<T> read(ID[] ids,
                 Transaction transaction)
          throws ForbiddenUserException,
                 FailedRequestException

Within an open transaction, read multiple persisted pojos and unmarshall their data into new pojo instances. If at least one instance is found but others are not, ignores the instances not found. While this returns a PojoPage, the PageSize will match the number of instances found, and will ignore getPageLength(). To paginate, send a smaller set of ids at a time.

Parameters:

ids - the unique identifiers of the pojos (the values of the field annotated with @Id)

transaction - the transaction in which this read is participating (will open a read lock on each document matched that is released when the transaction is committed or rolled back)

Returns:

a set of instances of the correct type populated with the persisted data. Since this call produces a finite set, only one page is returned and therefore PojoPage pagination methods will not be helpful as they would be from calls to search.

Throws:

ForbiddenUserException

FailedRequestException

readAll

PojoPage<T> readAll(long start)
             throws ForbiddenUserException,
                    FailedRequestException

Read one page of persisted pojos of the type managed by this PojoRepository and unmarshall their data into new pojo instances.

Parameters:

start - the offset of the first document in the page (where 1 is the first result)

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned just like calls to search.

Throws:

ForbiddenUserException

FailedRequestException

readAll

PojoPage<T> readAll(long start,
                    Transaction transaction)
             throws ForbiddenUserException,
                    FailedRequestException

Within an open transaction, read one page of persisted pojos of the type managed by this PojoRepository and unmarshall their data into new pojo instances.

Parameters:

start - the offset of the first document in the page (where 1 is the first result)

transaction - the transaction in which this read is participating (Will open a read lock on each document matched. The read lock is released when the transaction is committed or rolled back.)

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned just like calls to search.

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(long start,
                   java.lang.String... collections)
            throws ForbiddenUserException,
                   FailedRequestException

Find all persisted pojos of the type managed by this PojoRepository also in one of the specified collections and unmarshall their data into new pojo instances.

Parameters:

start - the offset of the first document in the page (where 1 is the first result)

collections - matches must belong to at least one of the specified collections

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned and the total estimated number of results is available from PojoPage.getTotalSize().

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(long start,
                   Transaction transaction,
                   java.lang.String... collections)
            throws ForbiddenUserException,
                   FailedRequestException

Within an open transaction, find all persisted pojos of the type managed by this PojoRepository also in one of the specified collections and unmarshall their data into new pojo instances.

Parameters:

start - the offset of the first document in the page (where 1 is the first result)

transaction - the transaction in which this search is participating (Will open a read lock on each document matched. The read lock is released when the transaction is committed or rolled back.)

collections - matches must belong to at least one of the specified collections

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned and the total estimated number of results is available from PojoPage.getTotalSize().

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(PojoQueryDefinition query,
                   long start)
            throws ForbiddenUserException,
                   FailedRequestException

Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances. If matches are returned which do not meet all the criteria, you may need to create appropriate indexes in the server to run your query unfiltered or run your query filtered by wrapping your query with filteredQuery.

Parameters:

query - the query which results much match (queries are run unfiltered by default)

start - the offset of the first document in the page (where 1 is the first result)

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned and the total estimated number of results is available from PojoPage.getTotalSize().

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(PojoQueryDefinition query,
                   long start,
                   Transaction transaction)
            throws ForbiddenUserException,
                   FailedRequestException

Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances. If matches are returned which do not meet all the criteria, you may need to create appropriate indexes in the server to run your query unfiltered or run your query filtered by wrapping your query with filteredQuery.

Parameters:

query - the query which results much match (queries are run unfiltered by default)

start - the offset of the first document in the page (where 1 is the first result)

transaction - the transaction in which this search is participating (Will open a read lock on each document matched. The read lock is released when the transaction is committed or rolled back.)

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned and the total estimated number of results is available from PojoPage.getTotalSize().

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(PojoQueryDefinition query,
                   long start,
                   SearchReadHandle searchHandle)
            throws ForbiddenUserException,
                   FailedRequestException

Throws:

ForbiddenUserException

FailedRequestException

search

PojoPage<T> search(PojoQueryDefinition query,
                   long start,
                   SearchReadHandle searchHandle,
                   Transaction transaction)
            throws ForbiddenUserException,
                   FailedRequestException

Within an open transaction, search persisted pojos of the type managed by this PojoRepository for matches to this query and unmarshall their data into new pojo instances. If matches are returned which do not meet all the criteria, you may need to create appropriate indexes in the server to run your query unfiltered or run your query filtered by wrapping your query with filteredQuery.

Parameters:

query - the query which results much match (queries are run unfiltered by default)

start - the offset of the first document in the page (where 1 is the first result)

searchHandle - the handle to populate with a search results payload equivalent to one returned by QueryManager.search

transaction - the transaction in which this search is participating (Will open a read lock on each document matched. The read lock is released when the transaction is committed or rolled back.)

Returns:

a page with a maximum of getPageLength() instances of the correct type populated with the persisted data. Since this call may match a large set, only one page of getPageLength() is returned and the total estimated number of results is available from PojoPage.getTotalSize().

Throws:

ForbiddenUserException

FailedRequestException

getDocumentUri

java.lang.String getDocumentUri(T pojo)

getQueryBuilder

PojoQueryBuilder<T> getQueryBuilder()

Get a PojoQueryBuilder for the type managed by this PojoRepository.

Returns:

a PojoQueryBuilder for the type managed by this PojoRepository

getPageLength

long getPageLength()

The number of instances per page returned when calling readAll or search (Default: 50).

Returns:

the max number of instances per page

setPageLength

void setPageLength(long length)

Set the number of instances per page returned when calling readAll or search.

Parameters:

length - the max number of instance per page