ServiceSelector
Date: 2016-02-08

org.apache.avalon.framework.service

## Interface ServiceSelector

-     public interface ServiceSelector

  A `ServiceSelector` selects `Object`s based on a supplied policy. The contract is that all the `Object`s implement the same role.
  See Also:
    `Serviceable`, `ServiceSelector`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isSelectable(java.lang.Object policy)` Check to see if a `Object` exists relative to the supplied policy.
    `void` | `release(java.lang.Object object)` Return the `Object` when you are finished with it.
    `java.lang.Object` | `select(java.lang.Object policy)` Select the `Object` associated with the given policy.

- - ### Method Detail

    - #### select

          java.lang.Object select(java.lang.Object policy)
                                  throws ServiceException

      Select the `Object` associated with the given policy. For instance, If the `ServiceSelector` has a `Generator` stored and referenced by a URL, the following call could be used:

           try
           {
               Generator input;
               input = (Generator)selector.select( new URL("foo://demo/url") );
           }
           catch (...)
           {
               ...
           }

      Parameters:
        `policy` - A criteria against which a `Object` is selected.
      Returns:
        an `Object` value
      Throws:
        `ServiceException` - If the requested `Object` cannot be supplied

    - #### isSelectable

          boolean isSelectable(java.lang.Object policy)

      Check to see if a `Object` exists relative to the supplied policy.
      Parameters:
        `policy` - a `Object` containing the selection criteria
      Returns:
        True if the component is available, False if it not.

    - #### release

          void release(java.lang.Object object)

      Return the `Object` when you are finished with it. This allows the `ServiceSelector` to handle the End-Of-Life Lifecycle events associated with the `Object`. Please note, that no Exception should be thrown at this point. This is to allow easy use of the ServiceSelector system without having to trap Exceptions on a release.
      Parameters:
        `object` - The `Object` we are releasing, may also be a `null` reference