Package edu.byu.hbll.box

Class BoxQuery

  • public class BoxQuery
extends Object
    Query for requesting documents from Box.

    There are two ways of querying box. The first is to request documents by id. When requesting by id, the limit is ignored. There will be a 1:1 representation of documents according to the ids. If a document is not processed for a given id, a placeholder will still appear for that id. Documents are always returned in the same order as the requested ids.

    The second query type harvests documents by requesting and filtering all documents according to the cursor, facets and limit instructions. Documents are always returned in cursor order. Only processed documents are returned. For this query type, the ids, process and wait clauses are ignored.

    If there are ids in the query, then the id query type is used.

    • Constructor Detail

      • BoxQuery

        public BoxQuery()
        Creates a new empty query.

      • BoxQuery

        public BoxQuery​(BoxQuery query)
        Copy constructor.
        Parameters:
        query - query to copy

      • BoxQuery

        public BoxQuery​(Collection<String> ids)
        Creates a new query with the given ids.
        Parameters:
        ids - the ids

      • BoxQuery

        public BoxQuery​(String... ids)
        Creates a new query with the given ids.
        Parameters:
        ids - the ids

    • Method Detail

      • addFacet

        public BoxQuery addFacet​(String name,
                         String value)
        Adds a filter facet. Facets across facet groups are ANDed. Facets within a facet group are ORed. Applicable only for harvest queries.
        Parameters:
        name - name of the facet group
        value - value of the facet
        Returns:
        this

      • addFacet

        public BoxQuery addFacet​(Facet facet)
        Adds filter facets. Facets across facet groups are ANDed. Facets within a facet group are ORed. Applicable only for harvest queries.
        Parameters:
        facet - the facet to add
        Returns:
        this

      • addFacets

        public BoxQuery addFacets​(Facet... facets)
        Adds filter facets. Facets across facet groups are ANDed. Facets within a facet group are ORed. Applicable only for harvest queries.
        Parameters:
        facets - the facets to add
        Returns:
        this

      • addFacets

        public BoxQuery addFacets​(Collection<? extends Facet> facets)
        Adds filter facets. Facets across facet groups are ANDed. Facets within a facet group are ORed. Applicable only for harvest queries.
        Parameters:
        facets - the facets to add
        Returns:
        this

      • addField

        public BoxQuery addField​(String field)
        Limit the document to only these fields. Dot notation.
        Parameters:
        field - the field to add
        Returns:
        this

      • addFields

        public BoxQuery addFields​(Collection<String> fields)
        Limit the document to only these fields. Dot notation.
        Parameters:
        fields - the fields to add
        Returns:
        this

      • addFields

        public BoxQuery addFields​(String... fields)
        Limit the document to only these fields. Dot notation.
        Parameters:
        fields - the fields to add
        Returns:
        this

      • addId

        public BoxQuery addId​(String id)
        Adds an id to this query.
        Parameters:
        id - the id to add
        Returns:
        this

      • addIds

        public BoxQuery addIds​(Collection<String> ids)
        Adds ids to this query.
        Parameters:
        ids - the ids to add
        Returns:
        this

      • addIds

        public BoxQuery addIds​(String... ids)
        Adds ids to this query.
        Parameters:
        ids - the ids to add
        Returns:
        this

      • addStatus

        public BoxQuery addStatus​(BoxDocument.Status status)
        Queries by these document statuses.
        Parameters:
        status - the status to add
        Returns:
        this

      • addStatuses

        public BoxQuery addStatuses​(BoxDocument.Status... statuses)
        Queries by these document statuses.
        Parameters:
        statuses - the statuses to set
        Returns:
        this

      • addStatuses

        public BoxQuery addStatuses​(Collection<BoxDocument.Status> statuses)
        Queries by these document statuses.
        Parameters:
        statuses - the statuses to set
        Returns:
        this

      • clearFacets

        public BoxQuery clearFacets()
        Clears all the facets.
        Returns:
        this

      • clearFields

        public BoxQuery clearFields()
        Clears all the fields.
        Returns:
        this

      • clearIds

        public BoxQuery clearIds()
        Clears all the ids.
        Returns:
        this

      • clearStatuses

        public BoxQuery clearStatuses()
        Clears all the statuses.
        Returns:
        this

      • getCursor

        public Optional<Long> getCursor()
        Returns the cursor. If null, the cursor was not explicitly set.
        Returns:
        the cursor

      • getCursorOrDefault

        public long getCursorOrDefault()
        Returns the cursor or the default cursor if cursor not set.
        Returns:
        the limit

      • getFacets

        public Set<Facet> getFacets()
        Returns the specified facets.
        Returns:
        the facets

      • getFields

        public Set<String> getFields()
        Returns the specified fields.
        Returns:
        the fields

      • getIds

        public List<String> getIds()
        Returns the specified ids.
        Returns:
        the ids

      • getLimit

        public Optional<Long> getLimit()
        Returns the limit. If null, no limit was specified. Null does not mean NO_LIMIT. It means a default limit should be used.
        Returns:
        the limit

      • getLimitOrDefault

        public long getLimitOrDefault()
        Returns the limit or the default limit if limit not set.
        Returns:
        the limit

      • getStatuses

        public Set<BoxDocument.Status> getStatuses()
        Returns the specified statuses.
        Returns:
        the statuses

      • getStatusesOrDefault

        public Set<BoxDocument.Status> getStatusesOrDefault()
        Returns the statuses or the default statuses if none set.
        Returns:
        the statuses

      • isHarvestQuery

        public boolean isHarvestQuery()
        Whether or not this is a harvest query rather than an ID query.
        Returns:
        whether or not is a harvest query

      • isIdQuery

        public boolean isIdQuery()
        Whether or not this is an ID query rather than harvest query.
        Returns:
        whether or not is an ID query

      • isProcess

        public Optional<Boolean> isProcess()
        Whether or not to ask Box to (re)process the document now and return the result. Not valid for harvest type queries
        Returns:
        the process

      • isWait

        public Optional<Boolean> isWait()
        Whether or not to wait for documents to be processed.
        Returns:
        the wait

      • setCursor

        public BoxQuery setCursor​(long cursor)
        Sets the cursor. Documents are ordered by cursor ascending so this is used for paging. Only documents greater than or equal to this cursor will be returned. Applicable only for harvest queries.
        Parameters:
        cursor - the cursor to set
        Returns:
        this

      • setCursor

        public BoxQuery setCursor​(Long cursor)
        Sets the cursor. Documents are ordered by cursor ascending so this is used for paging. Only documents greater than or equal to this cursor will be returned. Applicable only for harvest queries.
        Parameters:
        cursor - the cursor to set
        Returns:
        this

      • setDocumentOnly

        public BoxQuery setDocumentOnly()
        Clears any set fields and adds the document field.
        Returns:
        this

      • setFacets

        public BoxQuery setFacets​(Collection<? extends Facet> facets)
        Adds filter facets. Facets across facet groups are ANDed. Facets within a facet group are ORed. Applicable only for harvest queries.
        Parameters:
        facets - the facets to add
        Returns:
        this

      • setFields

        public BoxQuery setFields​(Collection<String> fields)
        Limit the document to only these fields. Dot notation.
        Parameters:
        fields - the fields to add
        Returns:
        this

      • setLimit

        public BoxQuery setLimit​(long limit)
        Limits the number of documents returned to no more than this number. This is effectively the page size. A limit of UNLIMITED means return all documents. Applicable only for harvest queries.
        Parameters:
        limit - the limit to set
        Returns:
        this

      • setLimit

        public BoxQuery setLimit​(Long limit)
        Limits the number of documents returned to no more than this number. This is effectively the page size. A limit of UNLIMITED means return all documents. Applicable only for harvest queries.
        Parameters:
        limit - the limit to set
        Returns:
        this

      • setMetadataOnly

        public BoxQuery setMetadataOnly()
        Clears any set fields and adds the box metadata field.
        Returns:
        this

      • setProcess

        public BoxQuery setProcess​(Boolean process)
        Whether or not to ask Box to (re)process the document now and return the result. Not valid for harvest type queries.
        Parameters:
        process - the process to set
        Returns:
        this

      • setUnlimited

        public BoxQuery setUnlimited()
        Sets the limit to UNLIMITED. Same as limit(BoxQuery.UNLIMITED).
        Returns:
        this

      • setWait

        public BoxQuery setWait​(Boolean wait)
        Whether or not to wait for Box to process the document before returning. The document is immediately returned if it is already processed. Not valid for harvest type queries. Default false.
        Parameters:
        wait - the wait to set
        Returns:
        this