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 Details

    • COMPONENT_REPO_IMPLEMENTATION

      static final 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:

    • COMPONENT_REPO_MODE

      static final 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:

    • COMPONENT_REPO_MODE_RELAXED

      static final String COMPONENT_REPO_MODE_RELAXED
      See COMPONENT_REPO_MODE
      See Also:

    • COMPONENT_REPO_MODE_STRICT

      static final String COMPONENT_REPO_MODE_STRICT
      See COMPONENT_REPO_MODE
      See Also:

  • Method Details

    • getRevision

      long getRevision(String componentName, boolean localOnly) throws 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:
      IOException

    • getRevision

      default long getRevision(String componentName) throws IOException
      Shorthand for getRevision(String, boolean) with a false second parameter.
      Throws:
      IOException

    • findComponents

      Collection<String> findComponents(X propertyExpression, boolean localOnly) throws 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:
      IOException

    • findComponents

      default Collection<String> findComponents(X propertyExpression) throws IOException
      shorthand for findComponents(X, boolean) with a false second parameter.
      Throws:
      IOException

    • getComponent

      IComponentDescriptor getComponent(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(String component)
      shorthand for getComponent(String, boolean) with a false second parameter.

    • retrieve

      File retrieve(String name, boolean localOnly) throws 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:
      IOException

    • retrieve

      default File retrieve(String name) throws IOException
      shorthand for retrieve(String, boolean) with a false second parameter.
      Throws:
      IOException

    • getModules

      Set<String> getModules(boolean localOnly) throws 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:
      IOException

    • getModules

      default Set<String> getModules() throws IOException
      Retrieve the set of modules provided by this repository
      Throws:
      IOException