IReferences

Interface to manage references stored in a map.

Description

The IReferences interface can be used to manage references stored in a map, and which can be passed to other components to establish dependencies between them.

Generally speaking, an IReferences object is a simple map, where keys are locators and values are component references. Thus, it allows you to add, remove and find components by their locators. Locators can be any values like integers, strings or component types.

Important points

  • Together with IReferenceable and IUnreferenceable interfaces it implements a Locator pattern that is used by PipServices toolkit for Inversion of Control to assign external dependencies to components.
  • Generally, the PipServices toolkit uses Descriptor as locators that match according to the following fields: group, type, kind, name and version.

Instance methods

find

Gets all component references that match specified locator.
Throws a ReferenceException when required is set to true but no references found.

List find(Object locator, boolean required) throws ReferenceException

  • locator: Object - the locator to find a reference by.
  • required: boolean - forces to raise an exception if no reference is found.
  • returns: List - a list with matching component references.

    getAll

    Gets all component references registered in this reference map.

    List getAll()

    • returns: List - a list with component references.

      getAllLocators

      Gets locators for all registered component references in this reference map.

      List getAllLocators()

      • returns: List - a list with component locators.

        getOneOptional

        Gets an optional component reference that matches specified locator.

        List getOptional(Object locator)

        • locator: Object - the locator to find references by.
        • returns: List - a matching component reference or null if nothing was found.

          getOneRequired

          Gets a required component reference that matches specified locator.
          Throws a ReferenceException when no references found.

          Object getOneRequired(Object locator) throws ReferenceException

          • locator: Object - the locator to find a reference by.
          • returns: Object - a matching component reference.

          getOptional

          Gets all component references that match specified locator.

          List getOptional(Object locator)

          • locator: Object - the locator to find references by.
          • returns: List - a list with matching component references or empty list if nothing was found.

            getRequired

            Gets all component references that match specified locator. At least one component reference must be present. If it doesn’t the method throws an error.
            Throws a ReferenceException when no references found.

            List getRequired(Object locator) throws ReferenceException

            • locator: Object - the locator to find references by.
            • returns: List - a list with matching component references.

              put

              Puts a new reference into this reference map.

              void put(Object locator, Object component) throws ApplicationException

              • locator: Object - a locator to find the reference by.
              • component: Object - a component reference to be added.

              remove

              Removes a previously added reference that matches specified locator. If many references match the locator, it removes only the first one. When all references shall be removed, use removeAll method instead.

              Object remove(Object locator) throws ApplicationException

              • locator: Object - a locator to remove reference
              • returns: Object - the removed component reference.

              removeAll

              Removes all component references that match the specified locator.

              List removeAll(Object locator) throws ApplicationException

              • locator: Object - the locator to remove references by.
              • returns: List - a list, containing all removed references.

                Examples

                {
   public class MyController implements IReferenceable {
      public IMyPersistence _persistence;
      ...
      public void setReferences(IReferences references) {
        this._persistence = (IMyPersistence)references.getOneRequired(
          new Descriptor("mygroup", "persistence", "*", "*", "1.0")
        );
      }
      ...
   }
 
   MyMongoDbPersistence persistence = new MyMongoDbPersistence();
 
   MyController controller = new MyController();
 
   References references = References.fromTuples(
     new Descriptor("mygroup", "persistence", "mongodb", "default", "1.0"), persistence,
     new Descriptor("mygroup", "controller", "default", "default", "1.0"), controller
   );
   controller.setReferences(references);
     }

                See also