Package org.pipservices3.commons.refer

Interface IReferences

All Known Implementing Classes:
References
public interface IReferences
Interface for a map that holds component references and passes them to components to establish dependencies with each other.

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.

The IReferences object is a simple map, where keys are locators and values are component references. It allows to add, remove and find components by their locators. Locators can be any values like integers, strings or component types. But most often PipServices toolkit uses Descriptor as locators that match by 5 fields: group, type, kind, name and version.

### Example ### 

 
  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:

  • Method Summary

    Modifier and Type
    Method
    Description
    <T> List<T>
    find(Class<T> type, Object locator, boolean required)
    Gets all component references that match specified locator and matching to the specified type.
    List<Object>
    find(Object locator, boolean required)
    Gets all component references that match specified locator.
    List<Object>
    getAll()
    Gets all component references registered in this reference map.
    List<Object>
    getAllLocators()
    Gets locators for all registered component references in this reference map.
    <T> T
    getOneOptional(Class<T> type, Object locator)
    Gets an optional component reference that matches specified locator and matching to the specified type.
    Object
    getOneOptional(Object locator)
    Gets an optional component reference that matches specified locator.
    <T> T
    getOneRequired(Class<T> type, Object locator)
    Gets a required component reference that matches specified locator and matching to the specified type.
    Object
    getOneRequired(Object locator)
    Gets a required component reference that matches specified locator.
    <T> List<T>
    getOptional(Class<T> type, Object locator)
    Gets all component references that match specified locator and matching to the specified type.
    List<Object>
    getOptional(Object locator)
    Gets all component references that match specified locator.
    <T> List<T>
    getRequired(Class<T> type, Object locator)
    Gets all component references that match specified locator.
    List<Object>
    getRequired(Object locator)
    Gets all component references that match specified locator.
    void
    put(Object locator, Object component)
    Puts a new reference into this reference map.
    Object
    remove(Object locator)
    Removes a previously added reference that matches specified locator.
    List<Object>
    removeAll(Object locator)
    Removes all component references that match the specified locator.

  • Method Details

    • put

      void put(Object locator, Object component) throws ApplicationException
      Puts a new reference into this reference map.
      Parameters:
      locator - a locator to find the reference by.
      component - a component reference to be added.
      Throws:
      ApplicationException - when errors occured.

    • remove

      Object remove(Object locator) throws ApplicationException
      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.
      Parameters:
      locator - a locator to remove reference
      Returns:
      the removed component reference.
      Throws:
      ApplicationException - when errors occured.
      See Also:

    • removeAll

      List<Object> removeAll(Object locator) throws ApplicationException
      Removes all component references that match the specified locator.
      Parameters:
      locator - the locator to remove references by.
      Returns:
      a list, containing all removed references.
      Throws:
      ApplicationException - when errors occured.

    • getAllLocators

      List<Object> getAllLocators()
      Gets locators for all registered component references in this reference map.
      Returns:
      a list with component locators.

    • getAll

      List<Object> getAll()
      Gets all component references registered in this reference map.
      Returns:
      a list with component references.

    • getOptional

      List<Object> getOptional(Object locator)
      Gets all component references that match specified locator.
      Parameters:
      locator - the locator to find references by.
      Returns:
      a list with matching component references or empty list if nothing was found.

    • getOptional

      <T> List<T> getOptional(Class<T> type, Object locator)
      Gets all component references that match specified locator and matching to the specified type.
      Parameters:
      type - the Class type that defined the type of the result.
      locator - the locator to find references by.
      Returns:
      a list with matching component references or empty list if nothing was found.

    • getRequired

      List<Object> getRequired(Object locator) throws ReferenceException
      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.
      Parameters:
      locator - the locator to find references by.
      Returns:
      a list with matching component references.
      Throws:
      ReferenceException - when no references found.

    • getRequired

      <T> List<T> getRequired(Class<T> type, Object locator) throws ReferenceException
      Gets all component references that match specified locator. At least one component reference must be present and matching to the specified type.

      If it doesn't the method throws an error.

      Parameters:
      type - the Class type that defined the type of the result.
      locator - the locator to find references by.
      Returns:
      a list with matching component references.
      Throws:
      ReferenceException - when no references found.

    • getOneOptional

      Object getOneOptional(Object locator)
      Gets an optional component reference that matches specified locator.
      Parameters:
      locator - the locator to find references by.
      Returns:
      a matching component reference or null if nothing was found.

    • getOneOptional

      <T> T getOneOptional(Class<T> type, Object locator)
      Gets an optional component reference that matches specified locator and matching to the specified type.
      Parameters:
      type - the Class type that defined the type of the result.
      locator - the locator to find references by.
      Returns:
      a matching component reference or null if nothing was found.

    • getOneRequired

      Object getOneRequired(Object locator) throws ReferenceException
      Gets a required component reference that matches specified locator.
      Parameters:
      locator - the locator to find a reference by.
      Returns:
      a matching component reference.
      Throws:
      ReferenceException - when no references found.

    • getOneRequired

      <T> T getOneRequired(Class<T> type, Object locator) throws ReferenceException
      Gets a required component reference that matches specified locator and matching to the specified type.
      Parameters:
      type - the Class type that defined the type of the result.
      locator - the locator to find a reference by.
      Returns:
      a matching component reference.
      Throws:
      ReferenceException - when no references found.

    • find

      List<Object> find(Object locator, boolean required) throws ReferenceException
      Gets all component references that match specified locator.
      Parameters:
      locator - the locator to find a reference by.
      required - forces to raise an exception if no reference is found.
      Returns:
      a list with matching component references.
      Throws:
      ReferenceException - when required is set to true but no references found.

    • find

      <T> List<T> find(Class<T> type, Object locator, boolean required) throws ReferenceException
      Gets all component references that match specified locator and matching to the specified type.
      Parameters:
      type - the Class type that defined the type of the result.
      locator - the locator to find a reference by.
      required - forces to raise an exception if no reference is found.
      Returns:
      a list with matching component references.
      Throws:
      ReferenceException - when required is set to true but no references found.