Class Language

java.lang.Object
org.logicmachine.rebl.common.KeyValue
org.logicmachine.rebl.language.Language
All Implemented Interfaces:
Maybe
public class Language extends KeyValue
Top-level class defining the entry-point into the language.

In particular, this class creates an instance of the Grammar associated with this language as well as the top-most scope instance and the default system exception handler.

  • Constructor Details

    • Language

      public Language(String languageName)
      Constructor, creating a new language instance of the given 'languageName'.

      Note that a top-level default scope instance will also be created along with the top-most default exception handler.
      Parameters:
      languageName - the name of this language

    • Language

      public Language(String languageName, Class<? extends Scope> scopeType)
      Constructor, creating a new language instance of the given 'languageName'.

      Note that a top-level default scope instance will also be created along with the top-most default exception handler.

      The type of scope instance created will be determined by the given 'scopeType'. However if 'scopeType' is null, the default scope type will be used.

      The default scope type will then be set to 'scopeType', provided 'scopeType' is non-null.
      Parameters:
      languageName - the name of this language
      scopeType - sets the default scope type (can be null)

  • Method Details

    • withLocale

      public Language withLocale(Locale locale)
      Setter method allowing a locale to be defined for this Language instance.

      This locale will influence the handling of dates, currency and number formats.
      Parameters:
      locale - specifies the locale to be used
      Returns:
      a handle to self to allow chaining

    • withLocale

      public Locale withLocale()
      Returns the locale associated with this Language instance.

      Note that the locale defaults to the system default.
      Returns:
      the current locale

    • withGrammar

      public Grammar withGrammar()
      Returns a handle to the grammar instance associated with this Language.
      Returns:
      a handle to the grammar instance

    • emptyScope

      public Scope emptyScope()
      Returns a handle to the empty scope instance.
      Returns:
      an empty scope

    • withDefaultScope

      public Scope withDefaultScope()
      Returns the top-level default scope instance for this language.

      This will be the first scope created.
      Returns:
      the (first) top-most scope instance added, or null if no scope currently exists

    • withScope

      public Scope withScope(String scopeName)
      Returns the scope associated with the given 'scopeName', or a non-null 'empty' scope instance on no match.
      Parameters:
      scopeName - holds the name of the required scope
      Returns:
      a handle to the specified scope or a non-null 'empty' scope instance on no match

    • registerScope

      public Scope registerScope(Scope scope)
      Stores the given scope entry.

      This method will throw an EmptyOrNullArgumentException if 'scopeName' is null or an IllegalArgumentException if a Scope with this 'scopeName' already exists.

      Note that the 'empty' scope name will never be registered.
      Parameters:
      scope - holds the new scope instance to add
      Returns:
      a handle to the 'scope' parameter

    • unregisterScope

      public Scope unregisterScope(Scope scope)
      Unregisters the given 'scope', closing any CloseableResources associated with this scope and clearing all related scope data; returning the parent of this scope (which may be a non-null 'empty' instance).
      Parameters:
      scope - handle to the scope to unregister
      Returns:
      a handle to the parent of this scope (which may be a non-null 'empty' instance)

    • scopeExists

      public boolean scopeExists(String scopeName)
      This method can be used to check if an existing Scope is associated with the given 'scopeName'.

      This method is intended to be used to prevent the creation of duplicate scope names.

      See also the 'addScope()' method, which calls this method automatically.
      Parameters:
      scopeName - the name of the scope to check (cannot be null or empty)
      Returns:
      true if an existing scope is associated with the given 'key'; false otherwise

    • withParallelActiveEntityForScope

      public ActiveEntity withParallelActiveEntityForScope(ActiveEntity activeEntity)
      This method should be used to associate any ActiveEntity instances which are running in parallel with their corresponding Scope. This is necessary to ensure that no attempt is made to clear the Scope until all outstanding threads have completed.
      Parameters:
      activeEntity - handle to the ActiveEntity which is running in parallel
      Returns:
      the given 'activeEntity' parameter, unchanged (to allow chaining)

    • getNumberOfPendingParallelActiveEntitiesForScope

      public int getNumberOfPendingParallelActiveEntitiesForScope(Scope scope)
      Returns a count of the number of parallel active entity instances associated with the given 'scope' which are currently running, pending completion. Returns zero if there are no such pending active entity instance associated with the given 'scope'.
      Parameters:
      scope - handle to the scope instance potentially holding parallel ActiveEntity instances
      Returns:
      a count of the number of active entity instances for the given 'scope'

    • getNextParallelActiveEntityForScope

      public ActiveEntity getNextParallelActiveEntityForScope(Scope scope)
      Returns the next parallel active entity. This active entity will be found by checking all threads associated with the given 'scope'. Returns null if no parallel active entities exist.
      Parameters:
      scope - handle to the scope containing the active entities
      Returns:
      the next available parallel active entity (associated with the given 'scope') to wait for, or null if no such parallel active entities exist

    • getNextParallelActiveEntity

      public ActiveEntity getNextParallelActiveEntity()
      Returns the next parallel active entity. This active entity will be found by checking all scopes and all threads. Returns null if no parallel active entities exist.
      Returns:
      the next available parallel active entity to wait for, or null if no such parallel active entities exist

    • waitForParallelActiveEntitiesForScope

      public void waitForParallelActiveEntitiesForScope(Scope scope)
      If any ActiveEntity instances associated with the given 'scope' have previously been declared as parallel, this method will wait until all such ActiveEntities have completed, before returning.

      This method will have no affect if there are no such parallel ActiveEntity instances associated with the given 'scope', or if all relevant threads have already completed.

      Once all relevant threads have completed, all such parallel threads will be unregistered. Therefore calling this method more than once will have no affect, since all relevant threads will be completed and removed after the first invocation.
      Parameters:
      scope - holds the scope to check for parallel active entities

    • removeAllParallelActiveEntitiesForThread

      public void removeAllParallelActiveEntitiesForThread(ActiveEntity activeEntity)
      Removes all of the active entities associated with the given 'thread'.
      Parameters:
      activeEntity - the parallel ActiveEntity to be removed (which identifies both the scope and thread)

    • removeParallelActiveEntitiesFromScope

      public void removeParallelActiveEntitiesFromScope(Scope scope)
      Unregisters the completed parallel ActiveEntities for the given 'scope'.

      This method is called automatically once the associated parallel active entities have completed.
      Parameters:
      scope - handle to the scope containing the completed parallel active entity instances

    • clearParallelActiveEntities

      public Language clearParallelActiveEntities()
      Clears the collection of parallel active entities (for all scopes).
      Returns:
      a handle to self to allow chaining

    • withGlobalEnvironmentObject

      public Language withGlobalEnvironmentObject(Object object)
      Allows the given environment object to be added to the global environment.
      Parameters:
      object - handle to the object to be added to the global environment
      Returns:
      a handle to self to allow chaining

    • withGlobalEnvironmentObject

      public Language withGlobalEnvironmentObject(EnvironmentObject object)
      Allows the given environment object to be added to the global environment.
      Parameters:
      object - handle to the environment object to be added to the global environment
      Returns:
      a handle to self to allow chaining

    • withGlobalEnvironmentObjects

      public Language withGlobalEnvironmentObjects(Object... objects)
      Allows the given environment objects to be added to the global environment.
      Parameters:
      objects - handle to the objects to be added to the global environment
      Returns:
      a handle to self to allow chaining

    • withGlobalEnvironmentObjects

      public Language withGlobalEnvironmentObjects(EnvironmentObject... objects)
      Allows the given environment objects to be added to the global environment.
      Parameters:
      objects - handle to the environment objects to be added to the global environment
      Returns:
      a handle to self to allow chaining

    • getGlobalEnvironmentObject

      public EnvironmentObject getGlobalEnvironmentObject(Object key)
      Returns the global environment object with the given 'key', or an empty non-null environment object on no match.
      Parameters:
      key - identifies the required global environment variable
      Returns:
      a non-null environment object

    • withGlobalObjects

      public List<EnvironmentObject> withGlobalObjects()
      Returns the set of objects within the global environment as a list of 'EnvironmentObject' objects.

      Note that this method is similar to the 'withGlobalEnvironmentObjects()' method, which just returns the same data but as an 'EnvironmentObjects' collection.
      Returns:
      the global environment objects

    • withGlobalEnvironmentObjects

      public EnvironmentObjects withGlobalEnvironmentObjects()
      Returns the set of global environment objects as a 'EnvironmentObjects' collection.

      Note that this method is similar to the 'withGlobalObjects()' method, which just returns the same data but as a list of 'EnvironmentObject' objects.
      Returns:
      the global environment objects

    • addToGlobalScope

      public Entities addToGlobalScope(Class<? extends Entity> clazz, Entities entities)
      Adds the 'entities' of the specified 'clazz' to the global scope.

      Note that this method is NOT thread-safe.

      Note also that this method will have no affect if 'clazz' or 'entities' are null.
      Parameters:
      clazz - specifies the type of the entities to be added
      entities - holds the entities to add
      Returns:
      the input 'entities' parameter, unchanged, to allow chaining

    • findWithinGlobalScope

      public Entity findWithinGlobalScope(Class<? extends Entity> clazz, Object key)
      Attempts to locate an object of the specified 'clazz' with the given 'key', within the global data.
      Parameters:
      clazz - specifies the type of data item required
      key - the key to search for
      Returns:
      a handle to the object of the specified type and with the given 'name' on match; or a non-null empty instance on no-match

    • clearGlobalScopeEntities

      public Language clearGlobalScopeEntities()
      Removes all of the entities stored within the global scope.
      Returns:
      a handle to self to allow chaining

    • removeAllScopeData

      public void removeAllScopeData()
      Removes all data associated with all scopes.

    • toString

      public String toString()
      Overrides:
      toString in class KeyValue

    • toString

      public String toString(int indentLevel)
      This method returns a detailed description of the business entities and business functionality contained within this language, indented to the specified level.
      Overrides:
      toString in class KeyValue
      Parameters:
      indentLevel - each line of the returned string will be indented to this level; where each level corresponds to 4 spaces
      Returns:
      a String representation of this instance

    • unregisterThisScope

      protected void unregisterThisScope(Scope scope)
      Unregisters the given 'scope' from this Language instance.

      Do not call this method directly. Rather, call the method 'Common.unregisterScope()' instead.

      See also the 'unregisterScope()' method in the Common class, which actually invokes this method as well as removing the given scope from the list of known parallel scopes (if applicable).
      Parameters:
      scope - handle to the scope to unregister

    • getNextParallelActiveEntity

      protected static ActiveEntity getNextParallelActiveEntity(Map<Thread,List<ActiveEntity>> entry)
      Returns the next parallel active entity from any of the threads within the given 'entry' map.
      Parameters:
      entry - holds the thread map containing the parallel active entities
      Returns:
      the next available parallel active entity to wait for, or null if no such parallel active entities exist