BlockInfo Specification

The BlockInfo file defines meta-information about a block, such as which services the block depends upon, and which services it can offer to other blocks.

The BlockInfo file is an XML file. It must be located in the same jar file as the block's implementing class. It must have the same name as the block's class, with the extention .xinfo. Thus, if you were looking up the BlockInfo for a block of class com.biz.cornerstone.blocks.MyBlock, you would look up the resource com/biz/cornerstone/blocks/MyBlock.xinfo in the jar file containing the block.

Below is an example BlockInfo file:

<?xml version="1.0"?>

<blockinfo>

    <block>
        <version>1.2.3</version>
    </block>

    <services>
        <service name="com.biz.cornerstone.services.MyService"
                 version="2.1.3" />
    </services>

    <dependencies>
        <dependency>
            <role>com.biz.cornerstone.services.Authorizer</role>
            <service name="com.biz.cornerstone.service.Authorizer"
                     version="1.2"/>
        </dependency>
        <dependency>
            <!-- note that role is not specified and defaults
                 to name of service. The service version is not
                 specified and it defaults to "1.0" -->
            <service name="com.biz.cornerstone.service.RoleMapper"/>
        </dependency>
    </dependencies>

</blockinfo>
            

You will notice that the information in the BlockInfo file is separated into three main sections:

• The <block> element, which defines the name and version of the block.
• The <services> element, which defines the services the block provides.
• The <dependencies> element, which defines the services the block uses.

The <block> element specifies the name and version of the block. The <block> element includes the following nested elements:

Element	Description
<name>	A descriptive name for the block. Optional.
<version>	The version of the block. Must be of the format major.minor.micro, where minor and micro are optional.
<schema-type>	The type of configuration schema provided with the block. Possible values depend on the Configuration Validator that Phoenix is using. This value is ignored by the default Configuration Validator. Optional.

The <services> element defines the services that the block can offer to other blocks. This element is optional; A block can choose to not offer any services to other blocks.

The <services> element should contain a nested <service> element for each service that the block provides. The <service> element takes the following attributes:

Name	Description
name	The service name. This is the fully qualified name of the service interface. The block must implement this interface. The service name is also used to identify the service in the BlockInfo files of blocks that use the service (see below).
version	The version of the service. This must be of the form major.minor.micro, where minor and micro are optional. Default value is 1.0.

The <dependencies> element defines the services that the block requires to operate. Phoenix provides these services to the block using the ServiceManager passed to the block's Serviceable.service() method.

The <dependencies> element should contain a nested <dependency> element for each service that the block uses. The <dependency> element takes the following nested elements:

The <service> element defines the expected service. The service element takes the following attributes:

Name	Description
name	The service name. This must be the fully qualified name of the service interface. The object returned by the ServiceManager is guaranteed to be castable to this interface. The service name is also used to identify the service in the BlockInfo file of blocks that provide the service (see above).
version	The expected version of the service. This must be of the form major.minor.micro, where minor and micro are optional. The default value is 1.0.

The <role> element specifies the role that the service plays. This must match the role name that the block supplies when it locates the service using ServiceManager.lookup( role ). The role name is also used in the Assembly File, to identify the dependency when connecting the block to the services it requires. The <role> element is optional, and the role name defaults to the service name.

The <management-access-points> element defines the management interfaces that the block provides. These interfaces are exported by Phoenix's management system to allow the block to be managed.

The <management-access-points> element must contain a <service> element for each of the block's management interfaces. The <service> element takes the following attributes:

Name	Description
name	The fully qualified name of the management interface. The block must implement this interface.
version	The version of the management interface. Default value is 1.0