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 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

    • getAppAsync

      public CompletableFuture<com.erudika.para.core.App> getAppAsync()
      Returns the App for the current access key (appid) asynchronously.
      Returns:
      a future of 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

    • getServerVersionAsync

      public CompletableFuture<String> getServerVersionAsync()
      Returns the Para server version asynchronously.
      Returns:
      a future of 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, Map<String, List<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, Map<String, List<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

    • invokeGetAsync

      public <T> CompletableFuture<T> invokeGetAsync(String resourcePath, Map<String, List<String>> params, Class<?> returnType)
      Invoke a GET request to the Para API asynchronously.
      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 future of a POJO

    • invokePostAsync

      public <T> CompletableFuture<T> invokePostAsync(String resourcePath, Object entity, Class<?> returnType)
      Invoke a POST request to the Para API asynchronously.
      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 future of a POJO

    • invokePutAsync

      public <T> CompletableFuture<T> invokePutAsync(String resourcePath, Object entity, Class<?> returnType)
      Invoke a PUT request to the Para API asynchronously.
      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 future of a POJO

    • invokePatchAsync

      public <T> CompletableFuture<T> invokePatchAsync(String resourcePath, Object entity, Class<?> returnType)
      Invoke a PATCH request to the Para API asynchronously.
      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 future of a POJO

    • invokeDeleteAsync

      public <T> CompletableFuture<T> invokeDeleteAsync(String resourcePath, Map<String, List<String>> params, Class<?> returnType)
      Invoke a DELETE request to the Para API asynchronously.
      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 future of a POJO

    • pagerToParams

      public Map<String, List<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.

    • createAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> createAsync(P obj)
      Persists an object to the data store asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the domain object
      Returns:
      a future of 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

    • readAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> readAsync(String type, String id)
      Retrieves an object from the data store asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      type - the type of the object
      id - the id of the object
      Returns:
      a future of 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

    • readAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> readAsync(String id)
      Retrieves an object from the data store asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      id - the id of the object
      Returns:
      a future of 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

    • updateAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> updateAsync(P obj)
      Updates an object permanently asynchronously. Supports partial updates.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the object to update
      Returns:
      a future of 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

    • deleteAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<Void> deleteAsync(P obj)
      Deletes an object permanently asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      obj - the object
      Returns:
      a future completed when the delete request finishes

    • 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

    • createAllAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> createAllAsync(List<P> objects)
      Saves multiple objects to the data store asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      objects - the list of objects to save
      Returns:
      a future of 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

    • readAllAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> readAllAsync(List<String> keys)
      Retrieves multiple objects from the data store asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      keys - a list of object ids
      Returns:
      a future of 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

    • updateAllAsync

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

    • deleteAll

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

    • deleteAllAsync

      public CompletableFuture<Void> deleteAllAsync(List<String> keys)
      Deletes multiple objects asynchronously.
      Parameters:
      keys - the ids of the objects to delete
      Returns:
      a future completed when all chunks finish

    • 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

    • listAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> listAsync(String type, com.erudika.para.core.utils.Pager... pager)
      Returns a list all objects found for the given type asynchronously.
      Type Parameters:
      P - the type of object
      Parameters:
      type - the type of objects to search for
      pager - a Pager
      Returns:
      a future of 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

    • findByIdAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> findByIdAsync(String id)
      Simple id search asynchronously.
      Type Parameters:
      P - type of the object
      Parameters:
      id - the id
      Returns:
      a future of 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

    • findByIdsAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findByIdsAsync(List<String> ids)
      Simple multi id search asynchronously.
      Type Parameters:
      P - type of the object
      Parameters:
      ids - a list of ids to search for
      Returns:
      a future of a list of objects 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

    • findNearbyAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findNearbyAsync(String type, String query, int radius, double lat, double lng, com.erudika.para.core.utils.Pager... pager)
      Searches for objects of a given type in a given radius asynchronously.
      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 future of 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

    • findPrefixAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findPrefixAsync(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 asynchronously.
      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 future of 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

    • findQueryAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findQueryAsync(String type, String query, com.erudika.para.core.utils.Pager... pager)
      Simple query string search. This is the basic search method asynchronously.
      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 future of 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

    • findNestedQueryAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findNestedQueryAsync(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" asynchronously.
      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 future of 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

    • findSimilarAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findSimilarAsync(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 asynchronously.
      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 future of 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

    • findTaggedAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findTaggedAsync(String type, String[] tags, com.erudika.para.core.utils.Pager... pager)
      Searches for objects tagged with one or more tags asynchronously.
      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 future of 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

    • findTagsAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findTagsAsync(String keyword, com.erudika.para.core.utils.Pager... pager)
      Searches for Tag objects asynchronously. 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 future of 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

    • findTermInListAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findTermInListAsync(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 asynchronously.
      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 future of 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 asynchronously.
      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 future of a list of objects found

    • findTermsAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findTermsAsync(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 asynchronously.
      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 future of 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

    • findWildcardAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findWildcardAsync(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 asynchronously.
      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 future of 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

    • getCountAsync

      public CompletableFuture<Long> getCountAsync(String type)
      Counts indexed objects asynchronously.
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      Returns:
      a future of 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

    • getCountAsync

      public CompletableFuture<Long> getCountAsync(String type, Map<String,?> terms)
      Counts indexed objects matching a set of terms/values asynchronously.
      Parameters:
      type - the type of object to search for. See ParaObject.getType()
      terms - a list of terms (property values)
      Returns:
      a future of 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

    • countLinksAsync

      public CompletableFuture<Long> countLinksAsync(com.erudika.para.core.ParaObject obj, String type2)
      Count the total number of links between this object and another type of object asynchronously.
      Parameters:
      obj - the object to execute this method on
      type2 - the other type of object
      Returns:
      a future of 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

    • getLinkedObjectsAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> getLinkedObjectsAsync(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 asynchronously.
      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 future of 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

    • findLinkedObjectsAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findLinkedObjectsAsync(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 asynchronously.
      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 future of 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

    • isLinkedAsync

      public CompletableFuture<Boolean> isLinkedAsync(com.erudika.para.core.ParaObject obj, String type2, String id2)
      Checks if this object is linked to another asynchronously.
      Parameters:
      obj - the object to execute this method on
      type2 - the other type
      id2 - the other id
      Returns:
      a future of 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

    • isLinkedAsync

      public CompletableFuture<Boolean> isLinkedAsync(com.erudika.para.core.ParaObject obj, com.erudika.para.core.ParaObject toObj)
      Checks if a given object is linked to this one asynchronously.
      Parameters:
      obj - the object to execute this method on
      toObj - the other object
      Returns:
      a future of 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

    • linkAsync

      public CompletableFuture<String> linkAsync(com.erudika.para.core.ParaObject obj, String id2)
      Links an object to this one in a many-to-many relationship asynchronously. 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:
      a future of 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

    • unlinkAsync

      public CompletableFuture<Void> unlinkAsync(com.erudika.para.core.ParaObject obj, String type2, String id2)
      Unlinks an object from this one asynchronously. 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
      Returns:
      a future of null

    • 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.

    • unlinkAllAsync

      public CompletableFuture<Void> unlinkAllAsync(com.erudika.para.core.ParaObject obj)
      Unlinks all objects that are linked to this one asynchronously.
      Parameters:
      obj - the object to execute this method on Only Linker objects are deleted. ParaObjects are left untouched.
      Returns:
      a future of null

    • 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

    • countChildrenAsync

      public CompletableFuture<Long> countChildrenAsync(com.erudika.para.core.ParaObject obj, String type2)
      Count the total number of child objects for this object asynchronously.
      Parameters:
      obj - the object to execute this method on
      type2 - the type of the other object
      Returns:
      a future of 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

    • getChildrenAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> getChildrenAsync(com.erudika.para.core.ParaObject obj, String type2, com.erudika.para.core.utils.Pager... pager)
      Returns all child objects linked to this object asynchronously.
      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 future of 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

    • getChildrenAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> getChildrenAsync(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 asynchronously.
      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 future of 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

    • findChildrenAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<List<P>> findChildrenAsync(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 asynchronously.
      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 future of 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.

    • deleteChildrenAsync

      public CompletableFuture<Void> deleteChildrenAsync(com.erudika.para.core.ParaObject obj, String type2)
      Deletes all child objects permanently asynchronously.
      Parameters:
      obj - the object to execute this method on
      type2 - the children's type.
      Returns:
      a future of null

    • newId

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

    • newIdAsync

      public CompletableFuture<String> newIdAsync()
      Generates a new unique id asynchronously.
      Returns:
      a future of a new id

    • getTimestamp

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

    • getTimestampAsync

      public CompletableFuture<Long> getTimestampAsync()
      Returns the current timestamp asynchronously.
      Returns:
      a future of 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

    • formatDateAsync

      public CompletableFuture<String> formatDateAsync(String format, Locale loc)
      Formats a date in a specific format asynchronously.
      Parameters:
      format - the date format
      loc - the locale instance
      Returns:
      a future of 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

    • noSpacesAsync

      public CompletableFuture<String> noSpacesAsync(String str, String replaceWith)
      Converts spaces to dashes asynchronously.
      Parameters:
      str - a string with spaces
      replaceWith - a string to replace spaces with
      Returns:
      a future of 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

    • stripAndTrimAsync

      public CompletableFuture<String> stripAndTrimAsync(String str)
      Strips all symbols, punctuation, whitespace and control chars from a string asynchronously.
      Parameters:
      str - a dirty string
      Returns:
      a future of a clean string

    • markdownToHtml

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

    • markdownToHtmlAsync

      public CompletableFuture<String> markdownToHtmlAsync(String markdownString)
      Converts Markdown to HTML asynchronously.
      Parameters:
      markdownString - Markdown
      Returns:
      a future of 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"

    • approximatelyAsync

      public CompletableFuture<String> approximatelyAsync(long delta)
      Returns the number of minutes, hours, months elapsed for a time delta (milliseconds) asynchronously.
      Parameters:
      delta - the time delta between two events, in milliseconds
      Returns:
      a future of 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

    • newKeysAsync

      public CompletableFuture<Map<String,String>> newKeysAsync()
      Generates a new set of access/secret keys asynchronously. Old keys are discarded and invalid after this.
      Returns:
      a future of 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.

    • typesAsync

      public CompletableFuture<Map<String,String>> typesAsync()
      Returns all registered types for this App asynchronously.
      Returns:
      a future of 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.

    • typesCountAsync

      public CompletableFuture<Map<String,Number>> typesCountAsync()
      Returns the number of objects for each existing type in this App asynchronously.
      Returns:
      a future of 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

    • meAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> meAsync()
      Returns a User or an App that is currently authenticated asynchronously.
      Type Parameters:
      P - an App or User
      Returns:
      a future of 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

    • meAsync

      public <P extends com.erudika.para.core.ParaObject> CompletableFuture<P> meAsync(String accessToken)
      Verifies a given JWT and returns the authenticated subject. This request will not remember the JWT in memory asynchronously.
      Type Parameters:
      P - an App or User
      Parameters:
      accessToken - a valid JWT access token
      Returns:
      a future of 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

    • voteUpAsync

      public CompletableFuture<Boolean> voteUpAsync(com.erudika.para.core.ParaObject obj, String voterid)
      Upvote an object and register the vote in DB asynchronously.
      Parameters:
      obj - the object to receive +1 votes
      voterid - the userid of the voter
      Returns:
      a future of 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

    • voteUpAsync

      public CompletableFuture<Boolean> voteUpAsync(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
      Upvote an object and register the vote in DB asynchronously.
      Parameters:
      obj - the object to receive +1 votes
      voterid - the userid of the voter
      expiresAfter - expires after seconds
      lockedAfter - locked after seconds
      Returns:
      a future of 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

    • voteDownAsync

      public CompletableFuture<Boolean> voteDownAsync(com.erudika.para.core.ParaObject obj, String voterid)
      Downvote an object and register the vote in DB asynchronously.
      Parameters:
      obj - the object to receive -1 votes
      voterid - the userid of the voter
      Returns:
      a future of 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

    • voteDownAsync

      public CompletableFuture<Boolean> voteDownAsync(com.erudika.para.core.ParaObject obj, String voterid, Integer expiresAfter, Integer lockedAfter)
      Downvote an object and register the vote in DB asynchronously.
      Parameters:
      obj - the object to receive -1 votes
      voterid - the userid of the voter
      expiresAfter - expires after seconds
      lockedAfter - locked after seconds
      Returns:
      a future of 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"

    • rebuildIndexAsync

      public CompletableFuture<Map<String,Object>> rebuildIndexAsync()
      Rebuilds the entire search index asynchronously.
      Returns:
      a future of 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"

    • rebuildIndexAsync

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

    • sendEmail

      public boolean sendEmail(List<String> toEmails, String subject, String fromEmail, String senderName, String message)
      Endpoint for sending transactional emails.
      Parameters:
      toEmails - list of email recipients
      subject - subject
      fromEmail - from email address
      senderName - sender name
      message - message body
      Returns:
      true if email was sent

    • sendEmailAsync

      public CompletableFuture<Boolean> sendEmailAsync(List<String> toEmails, String subject, String fromEmail, String senderName, String message)
      Endpoint for sending transactional emails asynchronously.
      Parameters:
      toEmails - list of email recipients
      subject - subject
      fromEmail - from email address
      senderName - sender name
      message - message body
      Returns:
      a future of true if email was sent

    • sendEmail

      public boolean sendEmail(List<String> toEmails, String subject, String fromEmail, String senderName, String message, boolean plaintextOnly, boolean markdownEnabled, InputStream file, String fileContentType)
      Endpoint for sending transactional emails.
      Parameters:
      toEmails - list of email recipients
      subject - subject
      fromEmail - from email address
      senderName - sender name
      message - message body
      plaintextOnly - true if plain text
      markdownEnabled - true if Markdown is enabled
      file - file input stream
      fileContentType - file MIME type
      Returns:
      true if email was sent

    • sendEmailAsync

      public CompletableFuture<Boolean> sendEmailAsync(List<String> toEmails, String subject, String fromEmail, String senderName, String message, boolean plaintextOnly, boolean markdownEnabled, InputStream file, String fileContentType)
      Endpoint for sending transactional emails asynchronously.
      Parameters:
      toEmails - list of email recipients
      subject - subject
      fromEmail - from email address
      senderName - sender name
      message - message body
      plaintextOnly - true if plain text
      markdownEnabled - true if Markdown is enabled
      file - file input stream
      fileContentType - file MIME type
      Returns:
      a future of true if email was sent

    • validationConstraints

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

    • validationConstraintsAsync

      public CompletableFuture<Map<String, Map<String, Map<String, Map<String,?>>>>> validationConstraintsAsync()
      Returns the validation constraints map asynchronously.
      Returns:
      a future of 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.

    • validationConstraintsAsync

      public CompletableFuture<Map<String, Map<String, Map<String, Map<String,?>>>>> validationConstraintsAsync(String type)
      Returns the validation constraints map asynchronously.
      Parameters:
      type - a type
      Returns:
      a future of 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.

    • addValidationConstraintAsync

      public CompletableFuture<Map<String, Map<String, Map<String, Map<String,?>>>>> addValidationConstraintAsync(String type, String field, com.erudika.para.core.validation.Constraint c)
      Add a new constraint for a given field asynchronously.
      Parameters:
      type - a type
      field - a field name
      c - the constraint
      Returns:
      a future of 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.

    • removeValidationConstraintAsync

      public CompletableFuture<Map<String, Map<String, Map<String, Map<String,?>>>>> removeValidationConstraintAsync(String type, String field, String constraintName)
      Removes a validation constraint for a given field asynchronously.
      Parameters:
      type - a type
      field - a field name
      constraintName - the name of the constraint to remove
      Returns:
      a future of 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

    • resourcePermissionsAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> resourcePermissionsAsync()
      Returns the permissions for all subjects and resources for current app asynchronously.
      Returns:
      a future of 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

    • resourcePermissionsAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> resourcePermissionsAsync(String subjectid)
      Returns only the permissions for a given subject (user) of the current app asynchronously.
      Parameters:
      subjectid - the subject id (user id)
      Returns:
      a future of 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

    • grantResourcePermissionAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> grantResourcePermissionAsync(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 asynchronously.
      Parameters:
      subjectid - subject id (user id)
      resourcePath - resource path or object type
      permission - a set of HTTP methods
      Returns:
      a future of 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

    • grantResourcePermissionAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> grantResourcePermissionAsync(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 asynchronously.
      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 future of 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

    • revokeResourcePermissionAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> revokeResourcePermissionAsync(String subjectid, String resourcePath)
      Revokes a permission for a subject, meaning they no longer will be able to access the given resource asynchronously.
      Parameters:
      subjectid - subject id (user id)
      resourcePath - resource path or object type
      Returns:
      a future of 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

    • revokeAllResourcePermissionsAsync

      public CompletableFuture<Map<String, Map<String, List<String>>>> revokeAllResourcePermissionsAsync(String subjectid)
      Revokes all permission for a subject asynchronously.
      Parameters:
      subjectid - subject id (user id)
      Returns:
      a future of 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

    • isAllowedToAsync

      public CompletableFuture<Boolean> isAllowedToAsync(String subjectid, String resourcePath, String httpMethod)
      Checks if a subject is allowed to call method X on resource Y asynchronously.
      Parameters:
      subjectid - subject id
      resourcePath - resource path or object type
      httpMethod - HTTP method name
      Returns:
      a future of true if allowed

    • appSettings

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

    • appSettingsAsync

      public CompletableFuture<Map<String,Object>> appSettingsAsync()
      Returns the map containing app-specific settings asynchronously.
      Returns:
      a future of 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.

    • appSettingsAsync

      public CompletableFuture<Map<String,Object>> appSettingsAsync(String key)
      Returns the value of a specific app setting (property) asynchronously.
      Parameters:
      key - a key
      Returns:
      a future of 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

    • addAppSettingAsync

      public CompletableFuture<Void> addAppSettingAsync(String key, Object value)
      Adds or overwrites an app-specific setting asynchronously.
      Parameters:
      key - a key
      value - a value
      Returns:
      a future of null

    • setAppSettings

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

    • setAppSettingsAsync

      public CompletableFuture<Void> setAppSettingsAsync(Map<?,?> settings)
      Overwrites all app-specific settings asynchronously.
      Parameters:
      settings - a key-value map of properties
      Returns:
      a future of null

    • removeAppSetting

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

    • removeAppSettingAsync

      public CompletableFuture<Void> removeAppSettingAsync(String key)
      Removes an app-specific setting asynchronously.
      Parameters:
      key - a key
      Returns:
      a future of null

    • 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().

    • signInAsync

      public CompletableFuture<com.erudika.para.core.User> signInAsync(String provider, String providerToken, boolean rememberJWT)
      Takes an identity provider access token and fetches the user data from that provider asynchronously. 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 future of 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:

    • signInAsync

      public CompletableFuture<com.erudika.para.core.User> signInAsync(String provider, String providerToken)
      Takes an identity provider access token and fetches the user data from that provider asynchronously.
      Parameters:
      provider - identity provider, e.g. 'facebook', 'google'...
      providerToken - access token from a provider like Facebook, Google, Twitter
      Returns:
      a future of 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

    • revokeAllTokensAsync

      public CompletableFuture<Boolean> revokeAllTokensAsync()
      Revokes all user tokens for a given user id asynchronously. 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:
      a future of 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> CompletableFuture<Void> updateAllPartially(BiFunction<List<Map<String,Object>>, com.erudika.para.core.utils.Pager, List<T>> paginatingFunc)
      Performs a partial batch update (async) 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
      Returns:
      a Future

    • updateAllPartially

      public <T extends com.erudika.para.core.ParaObject> CompletableFuture<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
      Returns:
      a Future