Package com.zfabrik.components.provider

## Interface IComponentsRepository

- All Known Subinterfaces:
    `IComponentsManager`
  All Known Implementing Classes:
    `AbstractComponentRepository`, `AbstractExtComponentRepository`

      public interface IComponentsRepository

  A component repository provides component meta data and resources to the z2 runtime. In other words: Component repositories define the system's view of the world.

  This interface must be implemented by a component repository in order to register at `IComponentsManager.registerRepository(int, IComponentsRepository)`.

  Component repository must be registered at meaningful times, preferrably early in the startup process, to make sure components will be found by others when queried.

  Component Repositories are prioritized and form a chain of responsibilities, given the repository with the higher priority preference over other ones with lower prio. In particular, a repository of higher priority is fully responsible of delegating calls to lower prio repositories.

  The following table lists priorities of common component repositories:

  Repository | priority
  --- | ---
  dev | 750
  l1 | 500

  Note that resources from repositories may be provided on-demand. Clients must call the `retrieve(String)` method to make sure component resources are available locally as files.

  Component descriptors however should be made available without possibly unrequired resource downloads, as the system will use the descriptors to implement component queries (see `findComponents(X)` ).

  Typically component repositories are structured in a two-level hierarchy comprising of a project name, i.e. some human-managable taxonomy uniquely identifying and separating namespaces, like `com.zfabrik.aproject` or `org.apache.log4j`, and a component name that separates technical components within the project.

  For example, a project holding a web application will typically also hold a Java component and maybe a data source definition. In that case, the structure within the repository may look like this (not showing other sibling projects):

       myproject/
              datasource.properties
              java/
                      z.properties
                      src.api/...
                      src.impl/...
              web/
                      z.properties
                      WebContent/
                              WEB-INF/
                                      web.xml
                              index.jsp

  In this case, components may be declared as simple property sets, e.g. `myproject/datasource` or as more complex components featuring a folder structure like `myproject/web`. This is a commonly implemented structure. Component repository implementations may however chose different storage structures for component properties and component hierarchies.
  Author:
    hb

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `COMPONENT_REPO_IMPLEMENTATION` | component repository implementations should add this property to component properties when providing a component descriptor so that the runtime can declare dependeny on the repository implementation component when providing a component resource.
    `static java.lang.String` | `COMPONENT_REPO_MODE` | System property indicating the operational mode the component repositories are used with.
    `static java.lang.String` | `COMPONENT_REPO_MODE_RELAXED` | See `COMPONENT_REPO_MODE`
    `static java.lang.String` | `COMPONENT_REPO_MODE_STRICT` | See `COMPONENT_REPO_MODE`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default java.util.Collection<java.lang.String>` | `findComponents​(X propertyExpression)` | shorthand for `findComponents(X, boolean)` with a `false` second parameter.
    `java.util.Collection<java.lang.String>` | `findComponents​(X propertyExpression, boolean localOnly)` | finds all components satisfying a query condition.
    `default IComponentDescriptor` | `getComponent​(java.lang.String component)` | shorthand for `getComponent(String, boolean)` with a `false` second parameter.
    `IComponentDescriptor` | `getComponent​(java.lang.String component, boolean localOnly)` | retrieves a component descriptor for a fully qualified component, e.g.
    `default java.util.Set<java.lang.String>` | `getModules()` | Retrieve the set of modules provided by this repository
    `java.util.Set<java.lang.String>` | `getModules​(boolean localOnly)` | Retrieve the set of modules provided by this repository.
    `default long` | `getRevision​(java.lang.String componentName)` | Shorthand for `getRevision(String, boolean)` with a `false` second parameter.
    `long` | `getRevision​(java.lang.String componentName, boolean localOnly)` | return the most current revision of the component as available by the provider.
    `default java.io.File` | `retrieve​(java.lang.String name)` | shorthand for `retrieve(String, boolean)` with a `false` second parameter.
    `java.io.File` | `retrieve​(java.lang.String name, boolean localOnly)` | Retrieve a component's resource folder.

- - ### Field Detail

    - #### COMPONENT_REPO_IMPLEMENTATION

          static final java.lang.String COMPONENT_REPO_IMPLEMENTATION

      component repository implementations should add this property to component properties when providing a component descriptor so that the runtime can declare dependeny on the repository implementation component when providing a component resource.
      See Also:
        Constant Field Values

    - #### COMPONENT_REPO_MODE

          static final java.lang.String COMPONENT_REPO_MODE

      System property indicating the operational mode the component repositories are used with. Supported values include
      RELAXED
        When set (case-independent), failure to remote connect will not stop repository operations but simply fail to discover updates. Attempts to access resources that have not been provided locally previously will still lead to errors
      STRICT
        When set (case-independent), failure to remote connect for update checks (if so required) will lead to exceptions thrown during repository operations and may render the system inoperational. This is the default setting and recommended for productive systems to ensure consistency.
      See Also:
        Constant Field Values

    - #### COMPONENT_REPO_MODE_RELAXED

          static final java.lang.String COMPONENT_REPO_MODE_RELAXED

      See `COMPONENT_REPO_MODE`
      See Also:
        Constant Field Values

    - #### COMPONENT_REPO_MODE_STRICT

          static final java.lang.String COMPONENT_REPO_MODE_STRICT

      See `COMPONENT_REPO_MODE`
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getRevision

          long getRevision​(java.lang.String componentName,
                           boolean localOnly)
                    throws java.io.IOException

      return the most current revision of the component as available by the provider. providers must be able to count revs. A rev <0 indicates that the package is not known to the repository.

      If localOnly is set to true, only this repository is looked up. Otherwise all repositories in the chain with lower priority are considered too.

      Throws:
        `java.io.IOException`

    - #### getRevision

          default long getRevision​(java.lang.String componentName)
                            throws java.io.IOException

      Shorthand for `getRevision(String, boolean)` with a `false` second parameter.
      Throws:
        `java.io.IOException`

    - #### findComponents

          java.util.Collection<java.lang.String> findComponents​(X propertyExpression,
                                                                boolean localOnly)
                                                         throws java.io.IOException

      finds all components satisfying a query condition. If localOnly is set to true, only this repository is queried. Otherwise all repositories in the chain with lower priority are considered too.

      If localOnly is set to true, only this repository is looked up. Otherwise all repositories in the chain with lower priority are considered too.

      Throws:
        `java.io.IOException`

    - #### findComponents

          default java.util.Collection<java.lang.String> findComponents​(X propertyExpression)
                                                                 throws java.io.IOException

      shorthand for `findComponents(X, boolean)` with a `false` second parameter.
      Throws:
        `java.io.IOException`

    - #### getComponent

          IComponentDescriptor getComponent​(java.lang.String component,
                                            boolean localOnly)

      retrieves a component descriptor for a fully qualified component, e.g. `<module>/java` for a Java component. If localOnly is set to true, only this repository is looked up. Otherwise all repositories in the chain with lower priority are considered too.

      If localOnly is set to true, only this repository is looked up. Otherwise all repositories in the chain with lower priority are considered too.

    - #### getComponent

          default IComponentDescriptor getComponent​(java.lang.String component)

      shorthand for `getComponent(String, boolean)` with a `false` second parameter.

    - #### retrieve

          java.io.File retrieve​(java.lang.String name,
                                boolean localOnly)
                         throws java.io.IOException

      Retrieve a component's resource folder. Every component has by definition a resource folder that reflects its repository defined content if any, or may be empty. This folder is a temporary structure, valid until the next time a component update will be fetched. Assuming these constraints this folder may be used to store temporary component data (e.g. as cache content).

      A call to this method always returns a folder. Depending on the component type however, this folder may be empty, contain a single z.properties file or more.

      If localOnly is set to true, only this repository is looked up. Otherwise all repositories in the chain with lower priority are considered too.

      Returns:
        the component's folder resource folder or `null`, if the component does not exist.
      Throws:
        `java.io.IOException`

    - #### retrieve

          default java.io.File retrieve​(java.lang.String name)
                                 throws java.io.IOException

      shorthand for `retrieve(String, boolean)` with a `false` second parameter.
      Throws:
        `java.io.IOException`

    - #### getModules

          java.util.Set<java.lang.String> getModules​(boolean localOnly)
                                              throws java.io.IOException

      Retrieve the set of modules provided by this repository. If `localOnly` is true, the methods returns only those modules that are provided by the very repository.
      Throws:
        `java.io.IOException`

    - #### getModules

          default java.util.Set<java.lang.String> getModules()
                                                      throws java.io.IOException

      Retrieve the set of modules provided by this repository
      Throws:
        `java.io.IOException`