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

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

      • 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