Package com.atlan.cache

Class AbstractMassCache<T extends AtlanObject>

java.lang.Object
com.atlan.cache.AbstractMassCache<T>
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
AtlanTagCache, CustomMetadataCache, GroupCache, RoleCache, UserCache
public abstract class AbstractMassCache<T extends AtlanObject> extends Object implements Closeable
Base class for reusable components that are common to all caches, where a cache is populated en-masse through batch refreshing.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected AtomicBoolean
    bulkRefresh
    Whether to refresh the cache by retrieving all objects up-front (true) or lazily, on-demand (false).
    protected final ReadWriteLock
    lock
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractMassCache(AtlanClient client, String cacheName)
    Define a new mass cache with the provided details.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    cache(String id, String sid, String name, T object)
    Add an entry to the cache.
    protected void
    cache(String id, String name, T object)
    Add an entry to the cache.
    void
    cacheById(String id)
    Wraps a single object lookup for the cache with necessary concurrency controls.
    void
    cacheByName(String name)
    Wraps a single object lookup for the cache with necessary concurrency controls.
    void
    cacheBySid(String sid)
    Wraps a single object lookup for the cache with necessary concurrency controls.
    void
    close()
    protected Stream<Map.Entry<String,T>>
    entrySet()
    Retrieve an iterable set of entries for the object-storing portion of the cache.
    AtomicBoolean
    getBulkRefresh()
    Whether to refresh the cache by retrieving all objects up-front (true) or lazily, on-demand (false).
    T
    getById(String id)
    Retrieve the actual object by Atlan-internal ID string.
    T
    getById(String id, boolean allowRefresh)
    Retrieve the actual object by Atlan-internal ID string.
    T
    getByName(String name)
    Retrieve the actual object by human-readable name.
    T
    getByName(String name, boolean allowRefresh)
    Retrieve the actual object by human-readable name.
    T
    getBySid(String sid)
    Retrieve the actual object by Atlan-internal secondary ID string.
    T
    getBySid(String sid, boolean allowRefresh)
    Retrieve the actual object by Atlan-internal secondary ID string.
    String
    getIdForName(String name)
    Translate the provided human-readable name to its Atlan-internal ID string.
    String
    getIdForName(String name, boolean allowRefresh)
    Translate the provided human-readable name to its Atlan-internal ID string.
    String
    getIdForSid(String sid)
    Translate the provided Atlan-internal secondary ID to its Atlan-internal ID string.
    String
    getIdForSid(String sid, boolean allowRefresh)
    Translate the provided Atlan-internal secondary ID to its Atlan-internal ID string.
    protected String
    getIdFromName(String name)
    Thread-safe cache retrieval of the ID of an object by its name.
    protected String
    getIdFromSid(String sid)
    Thread-safe cache retrieval of the ID of an object by its secondary ID.
    String
    getNameForId(String id)
    Translate the provided Atlan-internal ID string to the human-readable name for the object.
    String
    getNameForId(String id, boolean allowRefresh)
    Translate the provided Atlan-internal ID string to the human-readable name for the object.
    String
    getNameForSid(String sid)
    Translate the provided Atlan-internal secondary ID string to the human-readable name for the object.
    String
    getNameForSid(String sid, boolean allowRefresh)
    Translate the provided Atlan-internal secondary ID string to the human-readable name for the object.
    protected String
    getNameFromId(String id)
    Thread-safe cache retrieval of the name of an object by its ID.
    protected String
    getNameFromId(String id, boolean bypassReadLock)
    Thread-safe cache retrieval of the name of an object by its ID, when not bypassing the read lock.
    protected String
    getNameFromSid(String sid)
    Thread-safe cache retrieval of the name of an object by its secondary ID.
    protected T
    getObjectById(String id)
    Thread-safe cache retrieval of the object itself, by its ID.
    String
    getSidForName(String name)
    Translate the provided human-readable name to its Atlan-internal secondary ID string.
    String
    getSidForName(String name, boolean allowRefresh)
    Translate the provided human-readable name to its Atlan-internal secondary ID string.
    protected String
    getSidFromId(String id)
    Thread-safe cache retrieval of the secondary ID of an object by its ID.
    protected String
    getSidFromName(String name)
    Thread-safe cache retrieval of the secondary ID of an object by its name.
    protected boolean
    isEmpty()
    Whether the object-storing portion of the cache is empty (true) or not (false).
    boolean
    isIdKnown(String id)
    Checks whether the provided Atlan-internal ID string is known.
    boolean
    isNameKnown(String name)
    Checks whether the provided human-readable name is known.
    protected abstract void
    lookupById(String id)
    Logic to look up a single object for the cache.
    protected abstract void
    lookupByName(String name)
    Logic to look up a single object for the cache.
    protected void
    lookupBySid(String sid)
    Logic to look up a single object for the cache.
    void
    refresh()
    Wraps the cache refresh with necessary concurrency controls.
    protected abstract void
    refreshCache()
    Logic to refresh a specific cache en-masse (must be implemented).

    Methods inherited from class java.lang.Object

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

  • Field Details

    • lock

      protected final ReadWriteLock lock

    • bulkRefresh

      protected AtomicBoolean bulkRefresh
      Whether to refresh the cache by retrieving all objects up-front (true) or lazily, on-demand (false).

  • Constructor Details

    • AbstractMassCache

      public AbstractMassCache(AtlanClient client, String cacheName)
      Define a new mass cache with the provided details. Note: ideally, before using, also set the total capacity.
      Parameters:
      cacheName - name of the cache

  • Method Details

    • refresh

      public void refresh() throws AtlanException
      Wraps the cache refresh with necessary concurrency controls. Always call this method to actually update a cache, not the directly-implemented, cache-specific refreshCache.
      Throws:
      AtlanException - on any error communicating with Atlan to refresh the cache of objects

    • cacheById

      public void cacheById(String id) throws AtlanException
      Wraps a single object lookup for the cache with necessary concurrency controls.
      Parameters:
      id - unique internal identifier for the object
      Throws:
      AtlanException - on any error communicating with Atlan

    • cacheBySid

      public void cacheBySid(String sid) throws AtlanException
      Wraps a single object lookup for the cache with necessary concurrency controls.
      Parameters:
      sid - unique secondary internal identifier for the object
      Throws:
      AtlanException - on any error communicating with Atlan

    • cacheByName

      public void cacheByName(String name) throws AtlanException
      Wraps a single object lookup for the cache with necessary concurrency controls.
      Parameters:
      name - unique name for the object
      Throws:
      AtlanException - on any error communicating with Atlan

    • refreshCache

      protected abstract void refreshCache() throws AtlanException
      Logic to refresh a specific cache en-masse (must be implemented).
      Throws:
      AtlanException - on any error communicating with Atlan to refresh the cache of objects

    • lookupById

      protected abstract void lookupById(String id) throws AtlanException
      Logic to look up a single object for the cache.
      Parameters:
      id - unique internal identifier for the object
      Throws:
      AtlanException - on any error communicating with Atlan

    • lookupBySid

      protected void lookupBySid(String sid) throws AtlanException
      Logic to look up a single object for the cache. Note: by default this is not implemented (and will immediately error), so override it if you intend the cache to be populated by secondary ID lookups.
      Parameters:
      sid - unique secondary internal identifier for the object
      Throws:
      AtlanException - on any error communicating with Atlan
      InvalidRequestException - if not overridden with logic to update cache by secondary ID lookups

    • lookupByName

      protected abstract void lookupByName(String name) throws AtlanException
      Logic to look up a single object for the cache.
      Parameters:
      name - unique name for the object
      Throws:
      AtlanException - on any error communicating with Atlan

    • cache

      protected void cache(String id, String name, T object)
      Add an entry to the cache. This should only be called by the lookup methods, which themselves should never directly be invoked.
      Parameters:
      id - Atlan-internal ID (UUID)
      name - human-readable name
      object - the object to cache (if any)

    • cache

      protected void cache(String id, String sid, String name, T object)
      Add an entry to the cache. This should only be called by the lookup methods, which themselves should never directly be invoked.
      Parameters:
      id - Atlan-internal ID (UUID)
      sid - secondary Atlan-internal ID (hashed-string / nanoID)
      name - human-readable name
      object - the object to cache (if any)

    • isEmpty

      protected boolean isEmpty()
      Whether the object-storing portion of the cache is empty (true) or not (false).
      Returns:
      true if no objects are cached, otherwise false

    • entrySet

      protected Stream<Map.Entry<String,T>> entrySet()
      Retrieve an iterable set of entries for the object-storing portion of the cache.
      Returns:
      an iterable set of entries of objects that are cached

    • isNameKnown

      public boolean isNameKnown(String name)
      Checks whether the provided human-readable name is known. (Note: will not refresh the cache itself to determine this.)
      Parameters:
      name - human-readable name of the object
      Returns:
      true if the object is known, false otherwise

    • isIdKnown

      public boolean isIdKnown(String id)
      Checks whether the provided Atlan-internal ID string is known. (Note: will not refresh the cache itself to determine this.)
      Parameters:
      id - Atlan-internal ID string of the object
      Returns:
      true if the object is known, false otherwise

    • getIdFromName

      protected String getIdFromName(String name)
      Thread-safe cache retrieval of the ID of an object by its name.
      Parameters:
      name - of the object
      Returns:
      the ID of the object (if cached), or null

    • getNameFromId

      protected String getNameFromId(String id)
      Thread-safe cache retrieval of the name of an object by its ID.
      Parameters:
      id - of the object
      Returns:
      the name of the object (if cached), or null

    • getNameFromId

      protected String getNameFromId(String id, boolean bypassReadLock)
      Thread-safe cache retrieval of the name of an object by its ID, when not bypassing the read lock. Note: this allows you to bypass the read lock, in order to avoid potential deadlock situations, however you should ONLY do this if you know PRECISELY that you are still controlling the ordering of reads and writes (as concurrency safety will be bypassed when the read lock is bypassed) -- if you are not careful you may get a cache miss which would otherwise have been a cache hit.
      Parameters:
      id - of the object
      bypassReadLock - whether to bypass the read lock (necessary if we're reading while inside a write lock)
      Returns:
      the name of the object (if cached), or null

    • getIdFromSid

      protected String getIdFromSid(String sid)
      Thread-safe cache retrieval of the ID of an object by its secondary ID.
      Parameters:
      sid - of the object
      Returns:
      the ID of the object (if cached), or null

    • getSidFromId

      protected String getSidFromId(String id)
      Thread-safe cache retrieval of the secondary ID of an object by its ID.
      Parameters:
      id - of the object
      Returns:
      the secondary ID of the object (if cached), or null

    • getSidFromName

      protected String getSidFromName(String name)
      Thread-safe cache retrieval of the secondary ID of an object by its name.
      Parameters:
      name - of the object
      Returns:
      the secondary ID of the object (if cached), or null

    • getNameFromSid

      protected String getNameFromSid(String sid)
      Thread-safe cache retrieval of the name of an object by its secondary ID.
      Parameters:
      sid - of the object
      Returns:
      the name of the object (if cached), or null

    • getObjectById

      protected T getObjectById(String id)
      Thread-safe cache retrieval of the object itself, by its ID.
      Parameters:
      id - of the object
      Returns:
      the object itself (if cached), or null

    • getIdForName

      public String getIdForName(String name) throws AtlanException
      Translate the provided human-readable name to its Atlan-internal ID string.
      Parameters:
      name - human-readable name of the object
      Returns:
      unique Atlan-internal ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getIdForName

      public String getIdForName(String name, boolean allowRefresh) throws AtlanException
      Translate the provided human-readable name to its Atlan-internal ID string.
      Parameters:
      name - human-readable name of the object
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      unique Atlan-internal ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getIdForSid

      public String getIdForSid(String sid) throws AtlanException
      Translate the provided Atlan-internal secondary ID to its Atlan-internal ID string.
      Parameters:
      sid - Atlan-internal secondary ID
      Returns:
      unique Atlan-internal ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getIdForSid

      public String getIdForSid(String sid, boolean allowRefresh) throws AtlanException
      Translate the provided Atlan-internal secondary ID to its Atlan-internal ID string.
      Parameters:
      sid - Atlan-internal secondary ID
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      unique Atlan-internal ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getSidForName

      public String getSidForName(String name) throws AtlanException
      Translate the provided human-readable name to its Atlan-internal secondary ID string.
      Parameters:
      name - human-readable name of the object
      Returns:
      unique Atlan-internal secondary ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getSidForName

      public String getSidForName(String name, boolean allowRefresh) throws AtlanException
      Translate the provided human-readable name to its Atlan-internal secondary ID string.
      Parameters:
      name - human-readable name of the object
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      unique Atlan-internal secondary ID string for the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getNameForId

      public String getNameForId(String id) throws AtlanException
      Translate the provided Atlan-internal ID string to the human-readable name for the object.
      Parameters:
      id - Atlan-internal ID string
      Returns:
      human-readable name of the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getNameForId

      public String getNameForId(String id, boolean allowRefresh) throws AtlanException
      Translate the provided Atlan-internal ID string to the human-readable name for the object.
      Parameters:
      id - Atlan-internal ID string
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      human-readable name of the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getNameForSid

      public String getNameForSid(String sid) throws AtlanException
      Translate the provided Atlan-internal secondary ID string to the human-readable name for the object.
      Parameters:
      sid - Atlan-internal secondary ID string
      Returns:
      human-readable name of the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getNameForSid

      public String getNameForSid(String sid, boolean allowRefresh) throws AtlanException
      Translate the provided Atlan-internal secondary ID string to the human-readable name for the object.
      Parameters:
      sid - Atlan-internal secondary ID string
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      human-readable name of the object
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getById

      public T getById(String id) throws AtlanException
      Retrieve the actual object by Atlan-internal ID string.
      Parameters:
      id - Atlan-internal ID string
      Returns:
      the object with that ID
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no ID was provided for the object to retrieve

    • getById

      public T getById(String id, boolean allowRefresh) throws AtlanException
      Retrieve the actual object by Atlan-internal ID string.
      Parameters:
      id - Atlan-internal ID string
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      the object with that ID
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no ID was provided for the object to retrieve

    • getBySid

      public T getBySid(String sid) throws AtlanException
      Retrieve the actual object by Atlan-internal secondary ID string.
      Parameters:
      sid - Atlan-internal secondary ID string
      Returns:
      the object with that secondary ID
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no ID was provided for the object to retrieve

    • getBySid

      public T getBySid(String sid, boolean allowRefresh) throws AtlanException
      Retrieve the actual object by Atlan-internal secondary ID string.
      Parameters:
      sid - Atlan-internal secondary ID string
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      the object with that secondary ID
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no ID was provided for the object to retrieve

    • getByName

      public T getByName(String name) throws AtlanException
      Retrieve the actual object by human-readable name.
      Parameters:
      name - human-readable name of the object
      Returns:
      the object with that name
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • getByName

      public T getByName(String name, boolean allowRefresh) throws AtlanException
      Retrieve the actual object by human-readable name.
      Parameters:
      name - human-readable name of the object
      allowRefresh - whether to allow a refresh of the cache (true) or not (false)
      Returns:
      the object with that name
      Throws:
      AtlanException - on any API communication problem if the cache needs to be refreshed
      NotFoundException - if the object cannot be found (does not exist) in Atlan
      InvalidRequestException - if no name was provided for the object to retrieve

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • getBulkRefresh

      public AtomicBoolean getBulkRefresh()
      Whether to refresh the cache by retrieving all objects up-front (true) or lazily, on-demand (false).