Package org.openremote.model.asset

Interface AssetResource

@Path("asset") public interface AssetResource
Assetinvalid input: '<'?> access rules:
  • The superuser (the admin in the master realm) may access all assets.
  • A regular user may have roles that allow read, write, or no access to any assets within its authenticated realm.
  • A restricted user is linked to a subset of assets within its authenticated realm and may have roles that allow read and/or write access to some asset details (see UserAssetLink).

The only operations, always limited to linked assets, a restricted user is able to perform are:

  • Method Details

    • getCurrentUserAssets

      @GET @Path("user/current") @Produces("application/json") @RolesAllowed("read:assets") Asset<?>[] getCurrentUserAssets(@BeanParam RequestParams requestParams)
      Retrieve the linked assets of the currently authenticated user. If the request is made by the superuser, an empty result is returned. If the request is made by a regular user, but the user has no linked assets and is therefore not restricted, the assets without parent (root assets) of the authenticated realm are returned. Note that the assets returned from this operation are not completely loaded and the Asset.path and Asset.attributes are empty. Call get(org.openremote.model.http.RequestParams, java.lang.String) to retrieve all asset details.

    • getUserAssetLinks

      @GET @Path("user/link") @Produces("application/json") @RolesAllowed("read:assets") UserAssetLink[] getUserAssetLinks(@BeanParam RequestParams requestParams, @QueryParam("realm") String realm, @QueryParam("userId") String userId, @QueryParam("assetId") String assetId)
      Retrieve links between assets and users.

      The realm parameter is required, userId and assetId can be null.

      If the authenticated user is the superuser, assigned assets from any realm can be retrieved. Otherwise the authenticated realm must be the same as the given realm. A 403 status is returned if a regular user tries to get asset/user links in a realm different than its authenticated realm, or if the user is restricted. A 404 status is returned if the realm doesn't exist. A 400 status code is returned if the given user is not in the given realm. An empty result is returned if the user or asset doesn't exist.

      TODO: We could return the assets of a restricted user

    • createUserAssetLinks

      @POST @Path("user/link") @Consumes("application/json") @Produces("application/json") @RolesAllowed("write:assets") void createUserAssetLinks(@BeanParam RequestParams requestParams, List<UserAssetLink> userAssets)
      Create all of the specified links; they must all be for the same realm and user.

      If the authenticated user is the superuser, asset/user links in any realm can be created. Otherwise assets must be in the same realm as the authenticated user. A 403 status is returned if a regular user tries to create an asset/user link in a realm different than its authenticated realm, or if the user is restricted. A 400 status is returned if the user or asset or realm doesn't exist, or if the user is not in the realm.

    • deleteUserAssetLink

      @DELETE @Path("user/link/{realm}/{userId}/{assetId}") @RolesAllowed("write:assets") void deleteUserAssetLink(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId, @PathParam("assetId") String assetId)
      Delete a link between asset and user.

      The realm is required.

      If the authenticated user is the superuser, asset/user links from any realm can be deleted. Otherwise assets must be in the same realm as the authenticated user. A 403 status is returned if a regular user tries to delete an asset/user link in a realm different than its authenticated realm, or if the user is restricted. A 400 status is returned if the user or asset or realm doesn't exist.

    • deleteUserAssetLinks

      @POST @Path("user/link/delete") @Consumes("application/json") @RolesAllowed("write:assets") void deleteUserAssetLinks(@BeanParam RequestParams requestParams, List<UserAssetLink> userAssets)
      Delete all of the specified links; they must all be for the same realm and user.

      If the authenticated user is the superuser, asset/user links from any realm can be deleted. Otherwise assets must be in the same realm as the authenticated user. A 403 status is returned if a regular user tries to delete an asset/user link in a realm different than its authenticated realm, or if the user is restricted. A 400 status is returned if the user or asset or realm doesn't exist.

    • deleteAllUserAssetLinks

      @DELETE @Path("user/link/{realm}/{userId}") @Consumes("application/json") @Produces("application/json") @RolesAllowed("write:assets") void deleteAllUserAssetLinks(@BeanParam RequestParams requestParams, @PathParam("realm") String realm, @PathParam("userId") String userId)

    • get

      @GET @Path("{assetId}") @Produces("application/json") @RolesAllowed("read:assets") Asset<?> get(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId)
      Retrieve the asset. Regular users can only access assets in their authenticated realm, the superuser can access assets in other (all) realms. A 403 status is returned if a regular user tries to access an asset in a realm different than its authenticated realm, or if the user is restricted and the asset is not linked to the user. All asset details (path, attributes) will be populated, the asset is loaded completely.

    • getPartial

      @GET @Path("partial/{assetId}") @Produces("application/json") @RolesAllowed("read:assets") Asset<?> getPartial(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId)
      Same as get(org.openremote.model.http.RequestParams, java.lang.String) but only returns a partially loaded asset (no attributes or path)

    • update

      @PUT @Path("{assetId}") @Consumes("application/json") @Produces("application/json") @RolesAllowed("write:assets") Asset<?> update(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, Asset<?> asset)
      Updates the asset. Regular users can only update assets in their authenticated realm, the superuser can update assets in other (all) realms. A 403 status is returned if a regular user tries to update an asset in a realm different than its authenticated realm, or if the original or target realm is not accessible. A 403 status is returned if the user is restricted and the asset is not linked to the user. A 400 status is returned if the asset's parent doesn't exist. A 400 status is returned if a restricted user attempts to write private meta items of any attributes. If a restricted user tries to write asset properties or dynamic attributes or meta items of dynamic attributes which are not writable by a restricted user, such data is ignored. For more details on limitations of restricted users, see UserAssetLink.

    • writeAttributeValue

      @PUT @Path("{assetId}/attribute/{attributeName}") @Consumes("application/json") @Produces("application/json") jakarta.ws.rs.core.Response writeAttributeValue(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, @PathParam("attributeName") String attributeName, Object value)
      Updates an attribute of an asset. Regular users can only update assets in their authenticated realm, the superuser can update assets in other (all) realms. A 403 status is returned if a regular user tries to update an asset in a realm different than its authenticated realm, or if the user is restricted and the asset to update is not in the set of linked assets of the restricted user.

      If the asset or attribute doesn't exist then a 404 status is returned.

      If an attribute is marked as MetaItemType.ACCESS_PUBLIC_WRITE then the attribute can be written publicly

      This operation is ultimately asynchronous, any call will return before the actual attribute value is changed in any storage or downstream processors. Thus any constraint violation or processing error will not be returned from this method, query the system later to determine the actual state and outcome of the write operation. The version of the asset entity will not be incremented by this operation, thus concurrent updates can overwrite data undetected ("last commit wins").

    • writeAttributeValue

      @PUT @Path("{assetId}/attribute/{attributeName}/{timestamp}") @Consumes("application/json") @Produces("application/json") jakarta.ws.rs.core.Response writeAttributeValue(@BeanParam RequestParams requestParams, @PathParam("assetId") String assetId, @PathParam("attributeName") String attributeName, @PathParam("timestamp") Long timestamp, Object value)

    • writeAttributeValues

      @PUT @Consumes("application/json") @Produces("application/json") @Path("attributes") AttributeWriteResult[] writeAttributeValues(@BeanParam RequestParams requestParams, AttributeState[] attributeStates)

    • writeAttributeEvents

      @PUT @Consumes("application/json") @Produces("application/json") @Path("attributes/timestamp") AttributeWriteResult[] writeAttributeEvents(@BeanParam RequestParams requestParams, AttributeEvent[] attributeEvents)

    • create

      @POST @Consumes("application/json") @Produces("application/json") @RolesAllowed("write:assets") Asset<?> create(@BeanParam RequestParams requestParams, Asset<?> asset)
      Creates an asset. The identifier value of the asset can be provided, it should be a globally unique string value, and must be 22 characters long. If no identifier value is provided, a unique value will be generated by the system upon insert. Regular users can only create assets in their authenticated realm, the superuser can create assets in other (all) realms. A 403 status is returned if a regular user tries to create an asset in a realm different than its authenticated realm, or if the user is restricted. A 400 status is returned if the asset's parent or realm doesn't exist or if an ID is provided and an asset with this ID already exists.

    • delete

      @DELETE @Produces("application/json") @RolesAllowed("write:assets") void delete(@BeanParam RequestParams requestParams, @QueryParam("assetId") List<String> assetIds)
      Deletes an asset. Regular users can only delete assets in their authenticated realm, the superuser can delete assets in other (all) realms. A 403 status is returned if a regular user tries to delete an asset in a realm different than its authenticated realm, or if the user is restricted.

    • queryAssets

      @POST @Path("query") @Consumes("application/json") @Produces("application/json") Asset<?>[] queryAssets(@BeanParam RequestParams requestParams, AssetQuery query)
      Retrieve assets using an AssetQuery.

      If the authenticated user is the superuser then assets referenced in the query or returned by the query can be in any realm. Otherwise assets must be in the same realm as the authenticated user, and for a restricted user, the assets must be linked to the user. An empty result is returned if the user does not have access to the assets. What is populated on the returned assets is determined by the AssetQuery.select value.

    • updateParent

      @PUT @Path("{parentAssetId}/child") @Consumes("application/json") @Produces("application/json") @RolesAllowed("write:assets") void updateParent(@BeanParam RequestParams requestParams, @PathParam("parentAssetId") @NotNull(message="Parent reference required") @NotNull(message="Parent reference required") String parentId, @QueryParam("assetIds") @Size(min=1,message="At least one child to update parent reference") @Size(min=1,message="At least one child to update parent reference") List<String> assetIds)
      Change parent for a set of asset

    • updateNoneParent

      @DELETE @Path("/parent") @Produces("application/json") @RolesAllowed("write:assets") void updateNoneParent(@BeanParam RequestParams requestParams, @QueryParam("assetIds") @Size(min=1,message="At least one child to update parent reference") @Size(min=1,message="At least one child to update parent reference") List<String> assetIds)
      Remove parent reference from each asset referenced in the query parameter assetIds