Package pl.edu.icm.unity.engine.api.token

Interface TokensManagement

public interface TokensManagement
Tokens API allows for manipulating generic tokens. Token is a piece of information which is:
  • bound to an entity
  • has unique identifier
  • has type (e.g. OAuth access token)
  • can have expiration time, when it is removed
  • can contain additional, type specific data
Tokens are used by both engine and endpoint extension modules.

As this is a low level interface it allows for external transaction steering. All methods will join an existing transaction if it is present.

Author:
K. Benedyczak

  • Method Details

    • addToken

      void addToken(String type, String value, pl.edu.icm.unity.base.entity.EntityParam owner, byte[] contents, Date created, Date expires) throws pl.edu.icm.unity.base.identity.IllegalIdentityValueException, IllegalTypeException
      Adds a new token
      Parameters:
      type - type or category of the token
      created - creation timestamp. It is guaranteed to be stored with second precision, though implementation might also store the full time.
      expires - precision as in created case.
      Throws:
      pl.edu.icm.unity.base.identity.IllegalIdentityValueException
      IllegalTypeException

    • addToken

      void addToken(String type, String value, byte[] contents, Date created, Date expires) throws IllegalTypeException
      Adds a new token without owner
      Parameters:
      type - type or category of the token
      created - creation timestamp. It is guaranteed to be stored with second precision, though implementation might also store the full time.
      expires - precision as in created case.
      Throws:
      IllegalTypeException

    • removeToken

      void removeToken(String type, String value)
      Removes the token

    • updateToken

      void updateToken(String type, String value, Date expires, byte[] contents)
      Update the token. Only contents and expiration time can be updated - the type and value are used to look up a token for update.
      Parameters:
      expires - if null -> leave unchanged
      contents - if null -> leave unchanged

    • getTokenById

      pl.edu.icm.unity.base.token.Token getTokenById(String type, String value)
      Returns a specified token

    • getTokenByIdForUpdate

      pl.edu.icm.unity.base.token.Token getTokenByIdForUpdate(String type, String value)
      As getTokenById(String, String), but takes a database row lock (SELECT ... FOR UPDATE), held for the duration of the current transaction. Must be called inside an existing transaction which will follow up with a write, so that the whole read-decide-write sequence is atomic with regard to concurrent callers acting on the same token.

      Unlike getTokenById(String, String), this does NOT filter out an already-expired token - it is still returned (with Token.isExpired() true) rather than causing a TokenNotFoundException. Callers of this method are, by definition, about to make their own atomic decision and often need to distinguish "expired" from "never existed" themselves (e.g. to report a protocol-specific expiry error instead of a generic not-found one).

    • getOwnedTokens

      List<pl.edu.icm.unity.base.token.Token> getOwnedTokens(String type, pl.edu.icm.unity.base.entity.EntityParam entity) throws pl.edu.icm.unity.base.identity.IllegalIdentityValueException, IllegalTypeException
      Returns all tokens of the entity
      Throws:
      pl.edu.icm.unity.base.identity.IllegalIdentityValueException
      IllegalTypeException

    • getAllTokens

      List<pl.edu.icm.unity.base.token.Token> getAllTokens(String type)
      Returns:
      all tokens of a given type

    • getAllTokens

      List<pl.edu.icm.unity.base.token.Token> getAllTokens()
      Returns:
      all tokens

    • addTokenExpirationListener

      void addTokenExpirationListener(TokensManagement.TokenExpirationListener listener, String type)
      Adds a new listenr which is notified about expired tokens of a specified type