Package oracle.dbtools.plugin.api.di

## Enum AvailableDependencies

- java.lang.Object
- - java.lang.Enum<AvailableDependencies>
  - - oracle.dbtools.plugin.api.di.AvailableDependencies

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Comparable<AvailableDependencies>`

      public enum AvailableDependencies
      extends java.lang.Enum<AvailableDependencies>

  Enumerates the publicly available services that can be injected into plugins via the `Inject` annotation on a type's constructor. Unless otherwise noted these services will always be available.
  Author:
    cdivilly

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant | Description
    --- | ---
    `ANNOTATIONS` | Provide an API for working with `Annotation` instances.
    `CONFIGURATION` | Provides a `Configuration` instance appropriate for the backing store that the current request is targeted to.
    `CONNECTION` | Provides a `Connection` connected to the appropriate database pool and schema, inferred from mapping the request URL.
    `INSTANCE_LOCATOR` | Provides an API for discovering at run-time the available implementations of a service.
    `IO` | Provides `IOStreams` service for manipulating input and output streams.
    `JSON` | Provides access to the `JSONStreams` service, which can be used to parse character streams into JSON (using `JSONReader`) and to generate JSON using `JSONWriter`.
    `JSON_OBJECTS` | Provides access to the `JSONObjects` service, which can be used to build in memory representations of JSON object graphs.
    `LOCALE` | Provides the most preferred `Locale` for a request
    `LOCALE_PREFERENCE` | Provides a `LocalePreference` instance, which enumerates the preferred `Locale`s for a request from most to least preferred.
    `LOG` | Provides access to the the JDK `Logger` service.
    `PATH_TEMPLATES` | Provides methods for working with `PathTemplateMatch` instances

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.annotation.Annotation[]` | `constraints()` | The Annotations that may constrain the scope of the dependency
    `java.lang.Class<?>` | `type()` | The type of the dependency
    `static AvailableDependencies` | `valueOf​(java.lang.String name)` | Returns the enum constant of this type with the specified name.
    `static AvailableDependencies[]` | `values()` | Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class java.lang.Enum

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### ANNOTATIONS

          public static final AvailableDependencies ANNOTATIONS

      Provide an API for working with `Annotation` instances. This API may be useful in unit tests to define expected `Annotation` values.

      ### Usage

           @Provides
           class SomeTestFixture {
             @Inject
             SomeTestFixture(Annotations annotations) {
               this.expectedNamedAnnotation = annotations.literal(Named.class,"foo");
             }
             ...
           }

    - #### CONFIGURATION

          public static final AvailableDependencies CONFIGURATION

      Provides a `Configuration` instance appropriate for the backing store that the current request is targeted to. If this service is called from an `ApplicationScoped` service, then the global configuration is used.

      ### Usage

           @Provides
           @Dispatches(@PathTemplate("/some/service"))
           class SomeService extends HttpServlet {
             @Inject
             SomeService(Configuration conf) {
               this.conf = conf;
             }

             public void doGet(HttpServletRequest request,
                 HttpServletResponse response) throws ServletException, IOException {
               String setting = conf.get(SOME_CONFIG_SETTING);
               response.getWriter()
                   .println("The value of the setting is: " + setting);
             }

             private final Configuration conf;

             private final static String SOME_CONFIG_SETTING = "my.really.important.setting";
           }

      The above example retrieves the value of the setting and displays it in the response.

      N.B. Care must be exercised when working with `Configuration` instances to ensure that a vector to reveal sensitive configuration data is not created. For example if the value of `my.really.important.setting` is sensitive, then printing it's value in the response to a GET request is entirely inappropriate and dangerous. Similarly any code that allows an attacker to control over displaying of configuration data in the delivered response is dangerous.

    - #### CONNECTION

          public static final AvailableDependencies CONNECTION

      Provides a `Connection` connected to the appropriate database pool and schema, inferred from mapping the request URL. This dependency will only be available during processing of requests that have been mapped to a JDBC backing store.

      ### Usage

           @Provides
           @Dispatches(@PathTemplate("/some/service"))
           class SomeService extends HttpServlet {
             @Inject
             SomeService(Connection conn) {
               this.conn = conn;
             }

             public void doGet(HttpServletRequest request,
                 HttpServletResponse response) throws ServletException, IOException {
               PreparedStatement ps = conn.prepareStatement(
                   "select sys_context('USERENV','CURRENT_USER') from dual");
               ResultSet rs = ps.execute();
               rs.next();
               String user = rs.getString(1);
               response.getWriter().println("mapped database user is: " + user);
               rs.close();
               ps.close();
             }

             private final Connection conn;
           }

      A `Connection` can only be injected for request URLs where the runtime has been able to the map the URL to a database pool and schema. If the runtime was not able to map the URL to a database/schema, then it will not attempt to dispatch a service that depends on `Connection`, even if it's URL pattern matches the request URL.

      For example attempting to access the above service at:

           http://localhost:8080/ords/some/service

      Will result in a `404 Not Found` status because the URL does not contain enough information to identify a database/schema to map to.

      By contrast, the following URL:

           http://localhost:8080/ords/test_schema/some/service

      Will execute correctly assuming a schema named `test_schema` exists in the default database pool

    - #### IO

          public static final AvailableDependencies IO

      Provides `IOStreams` service for manipulating input and output streams.

    - #### JSON

          public static final AvailableDependencies JSON

      Provides access to the `JSONStreams` service, which can be used to parse character streams into JSON (using `JSONReader`) and to generate JSON using `JSONWriter`.

    - #### JSON_OBJECTS

          public static final AvailableDependencies JSON_OBJECTS

      Provides access to the `JSONObjects` service, which can be used to build in memory representations of JSON object graphs.

    - #### LOCALE

          public static final AvailableDependencies LOCALE

      Provides the most preferred `Locale` for a request

    - #### LOCALE_PREFERENCE

          public static final AvailableDependencies LOCALE_PREFERENCE

      Provides a `LocalePreference` instance, which enumerates the preferred `Locale`s for a request from most to least preferred.

    - #### LOG

          public static final AvailableDependencies LOG

      Provides access to the the JDK `Logger` service. All Logging must be done through this service.

      ### Usage

           @Provides
           class SomeService {
             @Inject
             SomeService(Logger log) {
               this.log = log;
             }

             public void someMethod() {
               log.info("doing something");
             }

             private final Logger log;
           }

    - #### PATH_TEMPLATES

          public static final AvailableDependencies PATH_TEMPLATES

      Provides methods for working with `PathTemplateMatch` instances

      ### Usage

           @Provides
           class SomeService {
             @Inject
             SomeService(PathTemplates pathTemplates) {
               this.pathTemplates = pathTemplates;
             }

             private final PathTemplates pathTemplates;
           }

    - #### INSTANCE_LOCATOR

          public static final AvailableDependencies INSTANCE_LOCATOR

      Provides an API for discovering at run-time the available implementations of a service. Typically it is preferred to directly inject service implementations via an `@Inject` annotated constructor, but there are occasional use cases where it can be useful to locate dependencies dynamically at run-time. For example it may be necessary to discover if a given dependency is available or has multiple providers.

      Usage of this API should be limited as overuse implies reliance on the Service Locator Pattern rather than the Dependency Injection Pattern.

      ### Usage

           @Provides
           class SomeService {
             @Inject
             SomeService(InstanceLocator locator) {
               boolean widgetAvailable = !locator.select(Widget.class)
                   .isUnsatisfied();
             }

             public void someMethod() {
               if (widgetAvailable) {
                 // go down the preferred code path
               } else {
                 // go down a fallback code path
               }
             }
           }

  - ### Method Detail

    - #### values

          public static AvailableDependencies[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (AvailableDependencies c : AvailableDependencies.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static AvailableDependencies valueOf​(java.lang.String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `java.lang.IllegalArgumentException` - if this enum type has no constant with the specified name
        `java.lang.NullPointerException` - if the argument is null

    - #### constraints

          public java.lang.annotation.Annotation[] constraints()

      The Annotations that may constrain the scope of the dependency
      Returns:
        Annotations that the depedency must be matche against

    - #### type

          public java.lang.Class<?> type()

      The type of the dependency
      Returns:
        dependency type