Package org.pipservices3.commons.refer

Class References

java.lang.Object
org.pipservices3.commons.refer.References
All Implemented Interfaces:
IReferences
public class References extends Object implements IReferences
The most basic implementation of IReferences to store and locate component references.

### 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:

  • Field Details

  • Constructor Details

    • References

      public References()

    • References

      public References(Object[] tuples)
      Creates a new instance of references and initializes it with references.
      Parameters:
      tuples - (optional) a list of values where odd elements are locators and the following even elements are component references

  • Method Details

    • put

      public void put(Object locator, Object component) throws NullPointerException
      Puts a new reference into this reference map.
      Specified by:
      put in interface IReferences
      Parameters:
      locator - a locator to find the reference by.
      component - a component reference to be added.
      Throws:
      NullPointerException

    • remove

      public Object remove(Object locator)
      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.
      Specified by:
      remove in interface IReferences
      Parameters:
      locator - a locator to remove reference
      Returns:
      the removed component reference.
      See Also:

    • removeAll

      public List<Object> removeAll(Object locator)
      Removes all component references that match the specified locator.
      Specified by:
      removeAll in interface IReferences
      Parameters:
      locator - the locator to remove references by.
      Returns:
      a list, containing all removed references.

    • getAllLocators

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

    • getAll

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

    • getOneOptional

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

    • getOneOptional

      public <T> T getOneOptional(Class<T> type, Object locator)
      Gets an optional component reference that matches specified locator and matching to the specified type.
      Specified by:
      getOneOptional in interface IReferences
      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

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

    • getOneRequired

      public <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.
      Specified by:
      getOneRequired in interface IReferences
      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.

    • getOptional

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

    • getOptional

      public <T> List<T> getOptional(Class<T> type, Object locator)
      Gets all component references that match specified locator and matching to the specified type.
      Specified by:
      getOptional in interface IReferences
      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

      public 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.
      Specified by:
      getRequired in interface IReferences
      Parameters:
      locator - the locator to find references by.
      Returns:
      a list with matching component references.
      Throws:
      ReferenceException - when no references found.

    • getRequired

      public <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.

      Specified by:
      getRequired in interface IReferences
      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.

    • find

      public List<Object> find(Object locator, boolean required) throws ReferenceException
      Gets all component references that match specified locator.
      Specified by:
      find in interface IReferences
      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

      public <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.
      Specified by:
      find in interface IReferences
      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.

    • clear

      public void clear()
      Clear the references list

    • fromTuples

      public static References fromTuples(Object... tuples) throws ReferenceException
      Creates a new References from a list of key-value pairs called tuples.
      Parameters:
      tuples - a list of values where odd elements are locators and the following even elements are component references
      Returns:
      a newly created References.
      Throws:
      ReferenceException - when no references found.