Class ParaClient

java.lang.Object
com.erudika.para.client.ParaClient
All Implemented Interfaces:
Closeable, AutoCloseable
public final class ParaClient extends Object implements Closeable
The Java REST client for communicating with a Para API server.
Author:
Alex Bogdanovski [[email protected]]

  • Constructor Summary

    Constructors
    Constructor
    Description
    ParaClient(String accessKey, String secretKey)
    Default constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAppSetting(String key, Object value)
    Adds or overwrites an app-specific setting.
    Map<String,Map<String,Map<String,Map<String,?>>>>
    addValidationConstraint(String type, String field, com.erudika.para.core.validation.Constraint c)
    Add a new constraint for a given field.
    String
    approximately(long delta)
    Returns the number of minutes, hours, months elapsed for a time delta (milliseconds).
    Map<String,Object>
    appSettings()
    Returns the map containing app-specific settings.
    Map<String,Object>
    appSettings(String key)
    Returns the value of a specific app setting (property).
    void
    close()
    Closes the underlying Jersey client and releases resources.
    Long
    countChildren(com.erudika.para.core.ParaObject obj, String type2)
    Count the total number of child objects for this object.
    Long
    countLinks(com.erudika.para.core.ParaObject obj, String type2)
    Count the total number of links between this object and another type of object.
    <P extends com.erudika.para.core.ParaObject>
    P
    create(P obj)
    Persists an object to the data store.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    createAll(List<P> objects)
    Saves multiple objects to the data store.
    <P extends com.erudika.para.core.ParaObject>
    void
    delete(P obj)
    Deletes an object permanently.
    void
    deleteAll(List<String> keys)
    Deletes multiple objects.
    void
    deleteChildren(com.erudika.para.core.ParaObject obj, String type2)
    Deletes all child objects permanently.
    <P extends com.erudika.para.core.ParaObject>
    P
    findById(String id)
    Simple id search.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findByIds(List<String> ids)
    Simple multi id search.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findChildren(com.erudika.para.core.ParaObject obj, String type2, String query, com.erudika.para.core.utils.Pager... pager)
    Search through all child objects.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findLinkedObjects(com.erudika.para.core.ParaObject obj, String type2, String field, String query, com.erudika.para.core.utils.Pager... pager)
    Searches through all linked objects in many-to-many relationships.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findNearby(String type, String query, int radius, double lat, double lng, com.erudika.para.core.utils.Pager... pager)
    Search for Address objects in a radius of X km from a given point.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findNestedQuery(String type, String field, String query, com.erudika.para.core.utils.Pager... pager)
    Searches within a nested field.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findPrefix(String type, String field, String prefix, com.erudika.para.core.utils.Pager... pager)
    Searches for objects that have a property which value starts with a given prefix.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findQuery(String type, String query, com.erudika.para.core.utils.Pager... pager)
    Simple query string search.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findSimilar(String type, String filterKey, String[] fields, String liketext, com.erudika.para.core.utils.Pager... pager)
    Searches for objects that have similar property values to a given text.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findTagged(String type, String[] tags, com.erudika.para.core.utils.Pager... pager)
    Searches for objects tagged with one or more tags.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findTags(String keyword, com.erudika.para.core.utils.Pager... pager)
    Searches for Tag objects.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findTermInList(String type, String field, List<String> terms, com.erudika.para.core.utils.Pager... pager)
    Searches for objects having a property value that is in list of possible values.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findTerms(String type, Map<String,?> terms, boolean matchAll, com.erudika.para.core.utils.Pager... pager)
    Searches for objects that have properties matching some given values.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    findWildcard(String type, String field, String wildcard, com.erudika.para.core.utils.Pager... pager)
    Searches for objects that have a property with a value matching a wildcard query.
    String
    formatDate(String format, Locale loc)
    Formats a date in a specific format.
    String
    getAccessToken()
    Returns the JWT access token if any.
    String
    getApiPath()
    Returns the API request path.
    com.erudika.para.core.App
    getApp()
    Returns the App for the current access key (appid).
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    getChildren(com.erudika.para.core.ParaObject obj, String type2, com.erudika.para.core.utils.Pager... pager)
    Returns all child objects linked to this object.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    getChildren(com.erudika.para.core.ParaObject obj, String type2, String field, String term, com.erudika.para.core.utils.Pager... pager)
    Returns all child objects linked to this object.
    int
    getChunkSize()
    Returns the batch chunk size.
    Long
    getCount(String type)
    Counts indexed objects.
    Long
    getCount(String type, Map<String,?> terms)
    Counts indexed objects matching a set of terms/values.
    String
    getEndpoint()
    Returns the endpoint URL.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    getItems(String at, Map<String,Object> result, com.erudika.para.core.utils.Pager... pager)
    Converts a list of Maps to a List of ParaObjects, at a given path within the JSON tree structure.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    getItemsFromList(List<?> result)
    Deserializes ParaObjects from a JSON array (the "items:[]" field in search results).
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    getLinkedObjects(com.erudika.para.core.ParaObject obj, String type2, com.erudika.para.core.utils.Pager... pager)
    Returns all objects linked to the given one.
    String
    getServerVersion()
    Returns the Para server version.
    long
    getTimestamp()
    Returns the current timestamp.
    Map<String,Map<String,List<String>>>
    grantResourcePermission(String subjectid, String resourcePath, EnumSet<com.erudika.para.core.App.AllowedMethods> permission)
    Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource.
    Map<String,Map<String,List<String>>>
    grantResourcePermission(String subjectid, String resourcePath, EnumSet<com.erudika.para.core.App.AllowedMethods> permission, boolean allowGuestAccess)
    Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource.
    <T> T
    invokeDelete(String resourcePath, jakarta.ws.rs.core.MultivaluedMap<String,String> params, Class<?> returnType)
    Invoke a DELETE request to the Para API.
    <T> T
    invokeGet(String resourcePath, jakarta.ws.rs.core.MultivaluedMap<String,String> params, Class<?> returnType)
    Invoke a GET request to the Para API.
    <T> T
    invokePatch(String resourcePath, Object entity, Class<?> returnType)
    Invoke a PATCH request to the Para API.
    <T> T
    invokePost(String resourcePath, Object entity, Class<?> returnType)
    Invoke a POST request to the Para API.
    <T> T
    invokePut(String resourcePath, Object entity, Class<?> returnType)
    Invoke a PUT request to the Para API.
    boolean
    isAllowedTo(String subjectid, String resourcePath, String httpMethod)
    Checks if a subject is allowed to call method X on resource Y.
    boolean
    isLinked(com.erudika.para.core.ParaObject obj, com.erudika.para.core.ParaObject toObj)
    Checks if a given object is linked to this one.
    boolean
    isLinked(com.erudika.para.core.ParaObject obj, String type2, String id2)
    Checks if this object is linked to another.
    String
    link(com.erudika.para.core.ParaObject obj, String id2)
    Links an object to this one in a many-to-many relationship.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    list(String type, com.erudika.para.core.utils.Pager... pager)
    Returns a list all objects found for the given type.
    String
    markdownToHtml(String markdownString)
    Converts Markdown to HTML.
    <P extends com.erudika.para.core.ParaObject>
    P
    me()
    Returns a User or an App that is currently authenticated.
    <P extends com.erudika.para.core.ParaObject>
    P
    me(String accessToken)
    Verifies a given JWT and returns the authenticated subject.
    String
    newId()
    Generates a new unique id.
    Map<String,String>
    newKeys()
    Generates a new set of access/secret keys.
    String
    noSpaces(String str, String replaceWith)
    Converts spaces to dashes.
    jakarta.ws.rs.core.MultivaluedMap<String,String>
    pagerToParams(com.erudika.para.core.utils.Pager... pager)
    Converts a Pager object to query parameters.
    <P extends com.erudika.para.core.ParaObject>
    P
    read(String id)
    Retrieves an object from the data store.
    <P extends com.erudika.para.core.ParaObject>
    P
    read(String type, String id)
    Retrieves an object from the data store.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    readAll(List<String> keys)
    Retrieves multiple objects from the data store.
    <T extends com.erudika.para.core.ParaObject>
    void
    readEverything(Function<com.erudika.para.core.utils.Pager,List<T>> paginatingFunc)
    Paginates through all objects and executes the provided function on the results.
    <T extends com.erudika.para.core.ParaObject>
    void
    readEverything(Function<com.erudika.para.core.utils.Pager,List<T>> paginatingFunc, int pageSize)
    Paginates through all objects and executes the provided function on the results.
    Map<String,Object>
    rebuildIndex()
    Rebuilds the entire search index.
    Map<String,Object>
    rebuildIndex(String destinationIndex)
    Rebuilds the entire search index.
    void
    removeAppSetting(String key)
    Removes an app-specific setting.
    Map<String,Map<String,Map<String,Map<String,?>>>>
    removeValidationConstraint(String type, String field, String constraintName)
    Removes a validation constraint for a given field.
    Map<String,Map<String,List<String>>>
    resourcePermissions()
    Returns the permissions for all subjects and resources for current app.
    Map<String,Map<String,List<String>>>
    resourcePermissions(String subjectid)
    Returns only the permissions for a given subject (user) of the current app.
    Map<String,Map<String,List<String>>>
    revokeAllResourcePermissions(String subjectid)
    Revokes all permission for a subject.
    boolean
    revokeAllTokens()
    Revokes all user tokens for a given user id.
    Map<String,Map<String,List<String>>>
    revokeResourcePermission(String subjectid, String resourcePath)
    Revokes a permission for a subject, meaning they no longer will be able to access the given resource.
    void
    setAccessToken(String token)
    Sets the JWT access token.
    void
    setApiPath(String path)
    Sets the API request path.
    void
    setAppSettings(Map<?,?> settings)
    Overwrites all app-specific settings.
    void
    setChunkSize(int chunkSize)
    Sets the chunk size for batch CRUD operations.
    void
    setEndpoint(String endpoint)
    Sets the host URL of the Para server.
    com.erudika.para.core.User
    signIn(String provider, String providerToken)
    Takes an identity provider access token and fetches the user data from that provider.
    com.erudika.para.core.User
    signIn(String provider, String providerToken, boolean rememberJWT)
    Takes an identity provider access token and fetches the user data from that provider.
    void
    signOut()
    Clears the JWT access token but token is not revoked.
    String
    stripAndTrim(String str)
    Strips all symbols, punctuation, whitespace and control chars from a string.
    void
    throwExceptionOnHTTPError(boolean enabled)
    Enable/disable exception throwing in ParaClient.
    Map<String,String>
    types()
    Returns all registered types for this App.
    Map<String,Number>
    typesCount()
    Returns the number of objects for each existing type in this App.
    void
    unlink(com.erudika.para.core.ParaObject obj, String type2, String id2)
    Unlinks an object from this one.
    void
    unlinkAll(com.erudika.para.core.ParaObject obj)
    Unlinks all objects that are linked to this one.
    <P extends com.erudika.para.core.ParaObject>
    P
    update(P obj)
    Updates an object permanently.
    <P extends com.erudika.para.core.ParaObject>
    List<P>
    updateAll(List<P> objects)
    Updates multiple objects.
    <T extends com.erudika.para.core.ParaObject>
    void
    updateAllPartially(BiFunction<List<Map<String,Object>>,com.erudika.para.core.utils.Pager,List<T>> paginatingFunc)
    Performs a partial batch update on all objects of given type.
    <T extends com.erudika.para.core.ParaObject>
    void
    updateAllPartially(BiFunction<List<Map<String,Object>>,com.erudika.para.core.utils.Pager,List<T>> paginatingFunc, int pageSize, int updateBatchSize)
    Performs a partial batch update on all objects of given type.
    Map<String,Map<String,Map<String,Map<String,?>>>>
    validationConstraints()
    Returns the validation constraints map.
    Map<String,Map<String,Map<String,Map<String,?>>>>
    validationConstraints(String type)
    Returns the validation constraints map.
    boolean
    voteDown(com.erudika.para.core.ParaObject obj, String voterid)
    Downvote an object and register the vote in DB.
    boolean
    voteDown(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
    Downvote an object and register the vote in DB.
    boolean
    voteUp(com.erudika.para.core.ParaObject obj, String voterid)
    Upvote an object and register the vote in DB.
    boolean
    voteUp(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
    Upvote an object and register the vote in DB.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ParaClient

      public ParaClient(String accessKey, String secretKey)
      Default constructor.
      Parameters:
      accessKey - app access key
      secretKey - app secret key

  • Method Details

    • setEndpoint

      public void setEndpoint(String endpoint)
      Sets the host URL of the Para server.
      Parameters:
      endpoint - the Para server location

    • close

      public void close()
      Closes the underlying Jersey client and releases resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • getApp

      public com.erudika.para.core.App getApp()
      Returns the App for the current access key (appid).
      Returns:
      the App object

    • getEndpoint

      public String getEndpoint()
      Returns the endpoint URL.
      Returns:
      the endpoint

    • setApiPath

      public void setApiPath(String path)
      Sets the API request path.
      Parameters:
      path - a new path

    • getApiPath

      public String getApiPath()
      Returns the API request path.
      Returns:
      the request path without parameters

    • getAccessToken

      public String getAccessToken()
      Returns the JWT access token if any.
      Returns:
      the JWT access token, or null if not signed in

    • getServerVersion

      public String getServerVersion()
      Returns the Para server version.
      Returns:
      the version of Para server

    • setAccessToken

      public void setAccessToken(String token)
      Sets the JWT access token.
      Parameters:
      token - a valid token

    • setChunkSize

      public void setChunkSize(int chunkSize)
      Sets the chunk size for batch CRUD operations. If chunkSize is greater than zero, any requests made to createAll(), readAll(), updateAll() and deleteAll() will be partitioned into chunks equal to this size. The chunked requests made to Para Server will be executed synchronously, and the results of all chunk operations are aggregated into a single response.
      Parameters:
      chunkSize - the number of objects per chunk

    • getChunkSize

      public int getChunkSize()
      Returns the batch chunk size.
      Returns:
      the chunk size used for batch CRUD operations

    • throwExceptionOnHTTPError

      public void throwExceptionOnHTTPError(boolean enabled)
      Enable/disable exception throwing in ParaClient.
      Parameters:
      enabled - if true, the client will throw an exception when an error response is received. If false, the error is only logged. Default is false.

    • invokeGet

      public <T> T invokeGet(String resourcePath, jakarta.ws.rs.core.MultivaluedMap<String,String> params, Class<?> returnType)
      Invoke a GET request to the Para API.
      Type Parameters:
      T - return type
      Parameters:
      resourcePath - the subpath after '/v1/', should not start with '/'
      params - query parameters
      returnType - the type of object to return
      Returns:
      a POJO

    • invokePost

      public <T> T invokePost(String resourcePath, Object entity, Class<?> returnType)
      Invoke a POST request to the Para API.
      Type Parameters:
      T - return type
      Parameters:
      resourcePath - the subpath after '/v1/', should not start with '/'
      entity - request body
      returnType - the type of object to return
      Returns:
      a POJO

    • invokePut

      public <T> T invokePut(String resourcePath, Object entity, Class<?> returnType)
      Invoke a PUT request to the Para API.
      Type Parameters:
      T - return type
      Parameters:
      resourcePath - the subpath after '/v1/', should not start with '/'
      entity - request body
      returnType - the type of object to return
      Returns:
      a POJO

    • invokePatch

      public <T> T invokePatch(String resourcePath, Object entity, Class<?> returnType)
      Invoke a PATCH request to the Para API.
      Type Parameters:
      T - return type
      Parameters:
      resourcePath - the subpath after '/v1/', should not start with '/'
      entity - request body
      returnType - the type of object to return
      Returns:
      a POJO

    • invokeDelete

      public <T> T invokeDelete(String resourcePath, jakarta.ws.rs.core.MultivaluedMap<String,String> params, Class<?> returnType)
      Invoke a DELETE request to the Para API.
      Type Parameters:
      T - return type
      Parameters:
      resourcePath - the subpath after '/v1/', should not start with '/'
      params - query parameters
      returnType - the type of object to return
      Returns:
      a POJO

    • pagerToParams

      public jakarta.ws.rs.core.MultivaluedMap<String,String> pagerToParams(com.erudika.para.core.utils.Pager... pager)
      Converts a Pager object to query parameters.
      Parameters:
      pager - a Pager
      Returns:
      list of query parameters

    • getItemsFromList

      public <P extends com.erudika.para.core.ParaObject> List<P> getItemsFromList(List<?> result)
      Deserializes ParaObjects from a JSON array (the "items:[]" field in search results).
      Type Parameters:
      P - type
      Parameters:
      result - a list of deserialized maps
      Returns:
      a list of ParaObjects

    • getItems

      public <P extends com.erudika.para.core.ParaObject> List<P> getItems(String at, Map<String,Object> result, com.erudika.para.core.utils.Pager... pager)
      Converts a list of Maps to a List of ParaObjects, at a given path within the JSON tree structure.
      Type Parameters:
      P - type
      Parameters:
      at - the path (field) where the array of objects is located
      result - the response body for an API request
      pager - a Pager object
      Returns:
      a list of ParaObjects

    • create

      public <P extends com.erudika.para.core.ParaObject> P create(P obj)
      Persists an object to the data store. If the object's type and id are given, then the request will be a PUT request and any existing object will be overwritten.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the domain object
      Returns:
      the same object with assigned id or null if not created.

    • read

      public <P extends com.erudika.para.core.ParaObject> P read(String type, String id)
      Retrieves an object from the data store.
      Type Parameters:
      P - the type of object
      Parameters:
      type - the type of the object
      id - the id of the object
      Returns:
      the retrieved object or null if not found

    • read

      public <P extends com.erudika.para.core.ParaObject> P read(String id)
      Retrieves an object from the data store.
      Type Parameters:
      P - the type of object
      Parameters:
      id - the id of the object
      Returns:
      the retrieved object or null if not found

    • update

      public <P extends com.erudika.para.core.ParaObject> P update(P obj)
      Updates an object permanently. Supports partial updates.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the object to update
      Returns:
      the updated object

    • delete

      public <P extends com.erudika.para.core.ParaObject> void delete(P obj)
      Deletes an object permanently.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the object

    • createAll

      public <P extends com.erudika.para.core.ParaObject> List<P> createAll(List<P> objects)
      Saves multiple objects to the data store.
      Type Parameters:
      P - the type of object
      Parameters:
      objects - the list of objects to save
      Returns:
      a list of objects

    • readAll

      public <P extends com.erudika.para.core.ParaObject> List<P> readAll(List<String> keys)
      Retrieves multiple objects from the data store.
      Type Parameters:
      P - the type of object
      Parameters:
      keys - a list of object ids
      Returns:
      a list of objects

    • updateAll

      public <P extends com.erudika.para.core.ParaObject> List<P> updateAll(List<P> objects)
      Updates multiple objects.
      Type Parameters:
      P - the type of object
      Parameters:
      objects - the objects to update
      Returns:
      a list of objects

    • deleteAll

      public void deleteAll(List<String> keys)
      Deletes multiple objects.
      Parameters:
      keys - the ids of the objects to delete

    • list

      public <P extends com.erudika.para.core.ParaObject> List<P> list(String type, com.erudika.para.core.utils.Pager... pager)
      Returns a list all objects found for the given type. The result is paginated so only one page of items is returned, at a time.
      Type Parameters:
      P - the type of object
      Parameters:
      type - the type of objects to search for
      pager - a Pager
      Returns:
      a list of objects

    • findById

      public <P extends com.erudika.para.core.ParaObject> P findById(String id)
      Simple id search.
      Type Parameters:
      P - type of the object
      Parameters:
      id - the id
      Returns:
      the object if found or null

    • findByIds

      public <P extends com.erudika.para.core.ParaObject> List<P> findByIds(List<String> ids)
      Simple multi id search.
      Type Parameters:
      P - type of the object
      Parameters:
      ids - a list of ids to search for
      Returns:
      a list of object found

    • findNearby

      public <P extends com.erudika.para.core.ParaObject> List<P> findNearby(String type, String query, int radius, double lat, double lng, com.erudika.para.core.utils.Pager... pager)
      Search for Address objects in a radius of X km from a given point.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      query - the query string
      radius - the radius of the search circle
      lat - latitude
      lng - longitude
      pager - a Pager
      Returns:
      a list of objects found

    • findPrefix

      public <P extends com.erudika.para.core.ParaObject> List<P> findPrefix(String type, String field, String prefix, com.erudika.para.core.utils.Pager... pager)
      Searches for objects that have a property which value starts with a given prefix.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      field - the property name of an object
      prefix - the prefix
      pager - a Pager
      Returns:
      a list of objects found

    • findQuery

      public <P extends com.erudika.para.core.ParaObject> List<P> findQuery(String type, String query, com.erudika.para.core.utils.Pager... pager)
      Simple query string search. This is the basic search method.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      query - the query string
      pager - a Pager
      Returns:
      a list of objects found

    • findNestedQuery

      public <P extends com.erudika.para.core.ParaObject> List<P> findNestedQuery(String type, String field, String query, com.erudika.para.core.utils.Pager... pager)
      Searches within a nested field. The objects of the given type must contain a nested field "nstd".
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      field - the name of the field to target (within a nested field "nstd")
      query - the query string
      pager - a Pager
      Returns:
      a list of objects found

    • findSimilar

      public <P extends com.erudika.para.core.ParaObject> List<P> findSimilar(String type, String filterKey, String[] fields, String liketext, com.erudika.para.core.utils.Pager... pager)
      Searches for objects that have similar property values to a given text. A "find like this" query.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      filterKey - exclude an object with this key from the results (optional)
      fields - a list of property names
      liketext - text to compare to
      pager - a Pager
      Returns:
      a list of objects found

    • findTagged

      public <P extends com.erudika.para.core.ParaObject> List<P> findTagged(String type, String[] tags, com.erudika.para.core.utils.Pager... pager)
      Searches for objects tagged with one or more tags.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      tags - the list of tags
      pager - a Pager
      Returns:
      a list of objects found

    • findTags

      public <P extends com.erudika.para.core.ParaObject> List<P> findTags(String keyword, com.erudika.para.core.utils.Pager... pager)
      Searches for Tag objects. This method might be deprecated in the future.
      Type Parameters:
      P - type of the object
      Parameters:
      keyword - the tag keyword to search for
      pager - a Pager
      Returns:
      a list of objects found

    • findTermInList

      public <P extends com.erudika.para.core.ParaObject> List<P> findTermInList(String type, String field, List<String> terms, com.erudika.para.core.utils.Pager... pager)
      Searches for objects having a property value that is in list of possible values.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      field - the property name of an object
      terms - a list of terms (property values)
      pager - a Pager
      Returns:
      a list of objects found

    • findTerms

      public <P extends com.erudika.para.core.ParaObject> List<P> findTerms(String type, Map<String,?> terms, boolean matchAll, com.erudika.para.core.utils.Pager... pager)
      Searches for objects that have properties matching some given values. A terms query.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      terms - a map of fields (property names) to terms (property values)
      matchAll - match all terms. If true - AND search, if false - OR search
      pager - a Pager
      Returns:
      a list of objects found

    • findWildcard

      public <P extends com.erudika.para.core.ParaObject> List<P> findWildcard(String type, String field, String wildcard, com.erudika.para.core.utils.Pager... pager)
      Searches for objects that have a property with a value matching a wildcard query.
      Type Parameters:
      P - type of the object
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      field - the property name of an object
      wildcard - wildcard query string. For example "cat*".
      pager - a Pager
      Returns:
      a list of objects found

    • getCount

      public Long getCount(String type)
      Counts indexed objects.
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      Returns:
      the number of results found

    • getCount

      public Long getCount(String type, Map<String,?> terms)
      Counts indexed objects matching a set of terms/values.
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      terms - a list of terms (property values)
      Returns:
      the number of results found

    • countLinks

      public Long countLinks(com.erudika.para.core.ParaObject obj, String type2)
      Count the total number of links between this object and another type of object.
      Parameters:
      obj - the object to execute this method on
      type2 - the other type of object
      Returns:
      the number of links for the given object

    • getLinkedObjects

      public <P extends com.erudika.para.core.ParaObject> List<P> getLinkedObjects(com.erudika.para.core.ParaObject obj, String type2, com.erudika.para.core.utils.Pager... pager)
      Returns all objects linked to the given one. Only applicable to many-to-many relationships.
      Type Parameters:
      P - type of linked objects
      Parameters:
      obj - the object to execute this method on
      type2 - type of linked objects to search for
      pager - a Pager
      Returns:
      a list of linked objects

    • findLinkedObjects

      public <P extends com.erudika.para.core.ParaObject> List<P> findLinkedObjects(com.erudika.para.core.ParaObject obj, String type2, String field, String query, com.erudika.para.core.utils.Pager... pager)
      Searches through all linked objects in many-to-many relationships.
      Type Parameters:
      P - type of linked objects
      Parameters:
      obj - the object to execute this method on
      type2 - type of linked objects to search for
      field - the name of the field to target (within a nested field "nstd")
      query - a query string
      pager - a Pager
      Returns:
      a list of linked objects matching the search query

    • isLinked

      public boolean isLinked(com.erudika.para.core.ParaObject obj, String type2, String id2)
      Checks if this object is linked to another.
      Parameters:
      obj - the object to execute this method on
      type2 - the other type
      id2 - the other id
      Returns:
      true if the two are linked

    • isLinked

      public boolean isLinked(com.erudika.para.core.ParaObject obj, com.erudika.para.core.ParaObject toObj)
      Checks if a given object is linked to this one.
      Parameters:
      obj - the object to execute this method on
      toObj - the other object
      Returns:
      true if linked

    • link

      public String link(com.erudika.para.core.ParaObject obj, String id2)
      Links an object to this one in a many-to-many relationship. Only a link is created. Objects are left untouched. The type of the second object is automatically determined on read.
      Parameters:
      obj - the object to execute this method on
      id2 - link to the object with this id
      Returns:
      the id of the Linker object that is created

    • unlink

      public void unlink(com.erudika.para.core.ParaObject obj, String type2, String id2)
      Unlinks an object from this one. Only a link is deleted. Objects are left untouched.
      Parameters:
      obj - the object to execute this method on
      type2 - the other type
      id2 - the other id

    • unlinkAll

      public void unlinkAll(com.erudika.para.core.ParaObject obj)
      Unlinks all objects that are linked to this one.
      Parameters:
      obj - the object to execute this method on Only Linker objects are deleted. ParaObjects are left untouched.

    • countChildren

      public Long countChildren(com.erudika.para.core.ParaObject obj, String type2)
      Count the total number of child objects for this object.
      Parameters:
      obj - the object to execute this method on
      type2 - the type of the other object
      Returns:
      the number of links

    • getChildren

      public <P extends com.erudika.para.core.ParaObject> List<P> getChildren(com.erudika.para.core.ParaObject obj, String type2, com.erudika.para.core.utils.Pager... pager)
      Returns all child objects linked to this object.
      Type Parameters:
      P - the type of children
      Parameters:
      obj - the object to execute this method on
      type2 - the type of children to look for
      pager - a Pager
      Returns:
      a list of ParaObject in a one-to-many relationship with this object

    • getChildren

      public <P extends com.erudika.para.core.ParaObject> List<P> getChildren(com.erudika.para.core.ParaObject obj, String type2, String field, String term, com.erudika.para.core.utils.Pager... pager)
      Returns all child objects linked to this object.
      Type Parameters:
      P - the type of children
      Parameters:
      obj - the object to execute this method on
      type2 - the type of children to look for
      field - the field name to use as filter
      term - the field value to use as filter
      pager - a Pager
      Returns:
      a list of ParaObject in a one-to-many relationship with this object

    • findChildren

      public <P extends com.erudika.para.core.ParaObject> List<P> findChildren(com.erudika.para.core.ParaObject obj, String type2, String query, com.erudika.para.core.utils.Pager... pager)
      Search through all child objects. Only searches child objects directly connected to this parent via the parentid field.
      Type Parameters:
      P - the type of children
      Parameters:
      obj - the object to execute this method on
      type2 - the type of children to look for
      query - a query string
      pager - a Pager
      Returns:
      a list of ParaObject in a one-to-many relationship with this object

    • deleteChildren

      public void deleteChildren(com.erudika.para.core.ParaObject obj, String type2)
      Deletes all child objects permanently.
      Parameters:
      obj - the object to execute this method on
      type2 - the children's type.

    • newId

      public String newId()
      Generates a new unique id.
      Returns:
      a new id

    • getTimestamp

      public long getTimestamp()
      Returns the current timestamp.
      Returns:
      a long number

    • formatDate

      public String formatDate(String format, Locale loc)
      Formats a date in a specific format.
      Parameters:
      format - the date format
      loc - the locale instance
      Returns:
      a formatted date

    • noSpaces

      public String noSpaces(String str, String replaceWith)
      Converts spaces to dashes.
      Parameters:
      str - a string with spaces
      replaceWith - a string to replace spaces with
      Returns:
      a string with dashes

    • stripAndTrim

      public String stripAndTrim(String str)
      Strips all symbols, punctuation, whitespace and control chars from a string.
      Parameters:
      str - a dirty string
      Returns:
      a clean string

    • markdownToHtml

      public String markdownToHtml(String markdownString)
      Converts Markdown to HTML.
      Parameters:
      markdownString - Markdown
      Returns:
      HTML

    • approximately

      public String approximately(long delta)
      Returns the number of minutes, hours, months elapsed for a time delta (milliseconds).
      Parameters:
      delta - the time delta between two events, in milliseconds
      Returns:
      a string like "5m", "1h"

    • newKeys

      public Map<String,String> newKeys()
      Generates a new set of access/secret keys. Old keys are discarded and invalid after this.
      Returns:
      a map of new credentials

    • types

      public Map<String,String> types()
      Returns all registered types for this App.
      Returns:
      a map of plural-singular form of all the registered types.

    • typesCount

      public Map<String,Number> typesCount()
      Returns the number of objects for each existing type in this App.
      Returns:
      a map of singular object type to object count.

    • me

      public <P extends com.erudika.para.core.ParaObject> P me()
      Returns a User or an App that is currently authenticated.
      Type Parameters:
      P - an App or User
      Returns:
      a User or an App

    • me

      public <P extends com.erudika.para.core.ParaObject> P me(String accessToken)
      Verifies a given JWT and returns the authenticated subject. This request will not remember the JWT in memory.
      Type Parameters:
      P - an App or User
      Parameters:
      accessToken - a valid JWT access token
      Returns:
      a User or an App

    • voteUp

      public boolean voteUp(com.erudika.para.core.ParaObject obj, String voterid)
      Upvote an object and register the vote in DB.
      Parameters:
      obj - the object to receive +1 votes
      voterid - the userid of the voter
      Returns:
      true if vote was successful

    • voteUp

      public boolean voteUp(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
      Upvote an object and register the vote in DB.
      Parameters:
      obj - the object to receive +1 votes
      voterid - the userid of the voter
      expiresAfter - expires after seconds
      lockedAfter - locked after seconds
      Returns:
      true if vote was successful

    • voteDown

      public boolean voteDown(com.erudika.para.core.ParaObject obj, String voterid)
      Downvote an object and register the vote in DB.
      Parameters:
      obj - the object to receive -1 votes
      voterid - the userid of the voter
      Returns:
      true if vote was successful

    • voteDown

      public boolean voteDown(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
      Downvote an object and register the vote in DB.
      Parameters:
      obj - the object to receive -1 votes
      voterid - the userid of the voter
      expiresAfter - expires after seconds
      lockedAfter - locked after seconds
      Returns:
      true if vote was successful

    • rebuildIndex

      public Map<String,Object> rebuildIndex()
      Rebuilds the entire search index.
      Returns:
      a response object with properties "tookMillis" and "reindexed"

    • rebuildIndex

      public Map<String,Object> rebuildIndex(String destinationIndex)
      Rebuilds the entire search index.
      Parameters:
      destinationIndex - an existing index as destination
      Returns:
      a response object with properties "tookMillis" and "reindexed"

    • validationConstraints

      public Map<String,Map<String,Map<String,Map<String,?>>>> validationConstraints()
      Returns the validation constraints map.
      Returns:
      a map containing all validation constraints.

    • validationConstraints

      public Map<String,Map<String,Map<String,Map<String,?>>>> validationConstraints(String type)
      Returns the validation constraints map.
      Parameters:
      type - a type
      Returns:
      a map containing all validation constraints for this type.

    • addValidationConstraint

      public Map<String,Map<String,Map<String,Map<String,?>>>> addValidationConstraint(String type, String field, com.erudika.para.core.validation.Constraint c)
      Add a new constraint for a given field.
      Parameters:
      type - a type
      field - a field name
      c - the constraint
      Returns:
      a map containing all validation constraints for this type.

    • removeValidationConstraint

      public Map<String,Map<String,Map<String,Map<String,?>>>> removeValidationConstraint(String type, String field, String constraintName)
      Removes a validation constraint for a given field.
      Parameters:
      type - a type
      field - a field name
      constraintName - the name of the constraint to remove
      Returns:
      a map containing all validation constraints for this type.

    • resourcePermissions

      public Map<String,Map<String,List<String>>> resourcePermissions()
      Returns the permissions for all subjects and resources for current app.
      Returns:
      a map of subject ids to resource names to a list of allowed methods

    • resourcePermissions

      public Map<String,Map<String,List<String>>> resourcePermissions(String subjectid)
      Returns only the permissions for a given subject (user) of the current app.
      Parameters:
      subjectid - the subject id (user id)
      Returns:
      a map of subject ids to resource names to a list of allowed methods

    • grantResourcePermission

      public Map<String,Map<String,List<String>>> grantResourcePermission(String subjectid, String resourcePath, EnumSet<com.erudika.para.core.App.AllowedMethods> permission)
      Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource.
      Parameters:
      subjectid - subject id (user id)
      resourcePath - resource path or object type
      permission - a set of HTTP methods
      Returns:
      a map of the permissions for this subject id

    • grantResourcePermission

      public Map<String,Map<String,List<String>>> grantResourcePermission(String subjectid, String resourcePath, EnumSet<com.erudika.para.core.App.AllowedMethods> permission, boolean allowGuestAccess)
      Grants a permission to a subject that allows them to call the specified HTTP methods on a given resource.
      Parameters:
      subjectid - subject id (user id)
      resourcePath - resource path or object type
      permission - a set of HTTP methods
      allowGuestAccess - if true - all unauthenticated requests will go through, 'false' by default.
      Returns:
      a map of the permissions for this subject id

    • revokeResourcePermission

      public Map<String,Map<String,List<String>>> revokeResourcePermission(String subjectid, String resourcePath)
      Revokes a permission for a subject, meaning they no longer will be able to access the given resource.
      Parameters:
      subjectid - subject id (user id)
      resourcePath - resource path or object type
      Returns:
      a map of the permissions for this subject id

    • revokeAllResourcePermissions

      public Map<String,Map<String,List<String>>> revokeAllResourcePermissions(String subjectid)
      Revokes all permission for a subject.
      Parameters:
      subjectid - subject id (user id)
      Returns:
      a map of the permissions for this subject id

    • isAllowedTo

      public boolean isAllowedTo(String subjectid, String resourcePath, String httpMethod)
      Checks if a subject is allowed to call method X on resource Y.
      Parameters:
      subjectid - subject id
      resourcePath - resource path or object type
      httpMethod - HTTP method name
      Returns:
      true if allowed

    • appSettings

      public Map<String,Object> appSettings()
      Returns the map containing app-specific settings.
      Returns:
      a map

    • appSettings

      public Map<String,Object> appSettings(String key)
      Returns the value of a specific app setting (property).
      Parameters:
      key - a key
      Returns:
      a map containing one element {"value": "the_value"} or an empty map.

    • addAppSetting

      public void addAppSetting(String key, Object value)
      Adds or overwrites an app-specific setting.
      Parameters:
      key - a key
      value - a value

    • setAppSettings

      public void setAppSettings(Map<?,?> settings)
      Overwrites all app-specific settings.
      Parameters:
      settings - a key-value map of properties

    • removeAppSetting

      public void removeAppSetting(String key)
      Removes an app-specific setting.
      Parameters:
      key - a key

    • signIn

      public com.erudika.para.core.User signIn(String provider, String providerToken, boolean rememberJWT)
      Takes an identity provider access token and fetches the user data from that provider. A new User object is created if that user doesn't exist. Access tokens are returned upon successful authentication using one of the SDKs from Facebook, Google, Twitter, etc. Note: Twitter uses OAuth 1 and gives you a token and a token secret. You must concatenate them like this: {oauth_token}:{oauth_token_secret} and use that as the provider access token.
      Parameters:
      provider - identity provider, e.g. 'facebook', 'google'...
      providerToken - access token from a provider like Facebook, Google, Twitter
      rememberJWT - it true the access token returned by Para will be stored locally and available through getAccessToken()
      Returns:
      a User object or null if something failed. The JWT is available on the returned User object via User.getPassword().

    • signIn

      public com.erudika.para.core.User signIn(String provider, String providerToken)
      Takes an identity provider access token and fetches the user data from that provider.
      Parameters:
      provider - identity provider, e.g. 'facebook', 'google'...
      providerToken - access token from a provider like Facebook, Google, Twitter
      Returns:
      a User object or null if something failed
      See Also:

    • signOut

      public void signOut()
      Clears the JWT access token but token is not revoked. Tokens can be revoked globally per user with revokeAllTokens().

    • revokeAllTokens

      public boolean revokeAllTokens()
      Revokes all user tokens for a given user id. This would be equivalent to "logout everywhere". Note: Generating a new API secret on the server will also invalidate all client tokens. Requires a valid existing token.
      Returns:
      true if successful

    • readEverything

      public <T extends com.erudika.para.core.ParaObject> void readEverything(Function<com.erudika.para.core.utils.Pager,List<T>> paginatingFunc)
      Paginates through all objects and executes the provided function on the results.
      Type Parameters:
      T - type of object
      Parameters:
      paginatingFunc - paginating function

    • readEverything

      public <T extends com.erudika.para.core.ParaObject> void readEverything(Function<com.erudika.para.core.utils.Pager,List<T>> paginatingFunc, int pageSize)
      Paginates through all objects and executes the provided function on the results.
      Type Parameters:
      T - type of object
      Parameters:
      paginatingFunc - paginating function
      pageSize - page size for pager (pager.limit)

    • updateAllPartially

      public <T extends com.erudika.para.core.ParaObject> void updateAllPartially(BiFunction<List<Map<String,Object>>,com.erudika.para.core.utils.Pager,List<T>> paginatingFunc)
      Performs a partial batch update on all objects of given type. This method encapsulates the specific logic for performing the batch update safely because updating while searching for objects can lead to bugs due to the fact that _docid values change on each update call.
      Type Parameters:
      T - type of object
      Parameters:
      paginatingFunc - paginating function

    • updateAllPartially

      public <T extends com.erudika.para.core.ParaObject> void updateAllPartially(BiFunction<List<Map<String,Object>>,com.erudika.para.core.utils.Pager,List<T>> paginatingFunc, int pageSize, int updateBatchSize)
      Performs a partial batch update on all objects of given type. This method encapsulates the specific logic for performing the batch update safely because updating while searching for objects can lead to bugs due to the fact that _docid values change on each update call.
      Type Parameters:
      T - type of object
      Parameters:
      paginatingFunc - paginating function which returns a list of object
      pageSize - page size for pager (pager.limit)
      updateBatchSize - batch size for updating objects