path

• Overview
• Attributes
• Child Elements
• Rendering Operations
• Examples
• Protocol Handlers
  • File
  • HTTP
• Nested Element Definitions
  • Include
    • Attributes
    • Rendering Operations
  • Exclude
    • Attributes
    • Rendering Operations

Overview

The <path> element can be used to define a list of resources that are used in a given context (defining the classpath of a Java application, for example). So the <path> element is a nested element that is always used in a given context. To select resources from a path you can define the protocol to use. Magnet provides two built-in protocols: file and http. The first one allows selecting files from the file system and the other allows accessing files through HTTP.

The attributes of the <path> element allow defining the location of the resources to select. You can also define the sorting order of the selected resources. Finally, using <include> and <exclude> child elements, you can refine the resources that are selected using pattern matching.

Attributes

The following lists the xml attributes of the path element:

Child Elements

The following lists the possible child xml elements the path element can hold:

Rendering Operations

When a <path> element is rendered, it performs the following operations in order:

1. Resolves the protocol, host and directory attributes (using variable interpolation).
2. Renders all the <include> child elements, if any.
3. Renders all the <exclude> child elements, if any.
4. Creates a protocol handler for the specified protocol.
5. Resolves the resources of the path using the protocol handler.

Examples

This first example creates a path element that uses the "file" protocol to select all the jar files from the directory ${user.dir}/lib:

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="PathExample1"
        description="This is a first path example.">
...
    <path directory="${user.dir}/lib">
        <include pattern="*.jar" />
    </path>
...
</magnet>

This second example shows a path element that uses the default "file" protocol to select all jar files from the ${user.dir}/lib directory except the file test.jar. All the selected files will be sorted in descending alphabetical order:

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="PathExample2"
        description="This is a second path example.">
...
    <path directory="${user.dir}/lib"
               sorting="descending">
        <include pattern="*.jar" />
        <exclude pattern="test.jar" />
    </path>
...
</magnet>

In this third example we see a path element that uses the "http" protocol to connect to the web server myserver on port 8080 in order to retrieve the interfaces.jar and utils.jar files from the commonlibs/ folder of the web server. For people that are used to the HTTP protocol, it is equivalent to doing get requetst on the URLs http://myserer:8080/commonlibs/interfaces.jar and http://myserer:8080/commonlibs/utils.jar.

<magnet xmlns:magnet="http://schemas.sapia-oss.org/magnet/"
        name="PathExample2"
        description="This is a second path example.">
...
    <path protocol="http" host="myserver:8080" directory="commonlibs/">
        <include pattern="interfaces.jar" />
        <include pattern="utils.jar" />
    </path>
...
</magnet>

Protocol Handlers

To be able to retrieve the resources specified in the <path> element, Magnet uses an entity called protocol handler. It is represented by the ProtocolHandlerIF interface. Such a handler is responsible of retrieving a collection of resources given in the path's configuration. Magnet comes with two implementations of this interface: the HttpProtocolHandler (supports http URL protocol) and the FileProtocolHandler (supports file URL protocol).

File

This is the default protocol handler when none is specified in a <path> element. The file protocol handler contains some specific logic that pertains to the nature of using the file system to retrieve resources. Here is the list of the these special rules:

• The directory attribute can be absolute or can be relative to the value of the ${user.dir} system property. For more details, see the documentation of the java.io.File class.
• If the <path> element contains no <include> sub elements, then it will select the directory itself has the resource. It is useful if one wants to select a directory that contains .class files.
• To resolve the patterns of the <include> and <exclude> elements, Magnet uses an internal Ant class called DirectoryScanner. Basically a "*" matches zero or more characters and a "?" matches one character. It also defines the "**" pattern that match multiple directory levels. For more detail see the ant manual.

HTTP

The HTTP protocol allows retrieving resources from a web server. It also has special rules:

• If the host attribute of the <path> element is not specified, this protocol handler will connect to localhsot on port 80.
• Pattern macthing is not available to retrieve HTTP resources. Each file must be specified using <include> elements.

Nested Element Definitions

Include

The <include> element defines a resource to select in a <path> element. It's pattern attribute is used to specify the name of the resource. A pattern matching expression can be use instead of a specific name to select more than one resource.

Attributes

Rendering Operations

When an <include> element is rendered, it performs the following operations in order:

1. Resolves the pattern attribute (using variable interpolation).

Exclude

The <exclude> element defines a resource to exclude from a <path> element. It's pattern attribute is used to specify the name of the resource. A pattern matching expression can be use instead of a specific name to select more than one resource.

Attributes

Rendering Operations

When an <exclude> element is rendered, it performs the following operations in order:

1. Resolves the pattern attribute (using variable interpolation).