1.2. LOCKSS Plugin Format#

A LOCKSS plugin is expressed as a mapping from keys to values. Except for rare exceptions that are built into the LOCKSS software, LOCKSS plugins consist of an XML file containing these key-value pairs, accompanied by optional Java class files (compiled Java code), bundled together in a JAR file (a Java-specific Zip file).

The XML format of the plugin is a single <map> element, containing any number of map entries expressed as <entry> elements. Each map entry is a key-value pair, namely a plugin key which must be the first child of the <entry> element and must be of type String, and a plugin value which must be the second child of the <entry> element. See the Plugin Value Types for more about possible plugin values.

The order of the key-value pairs does not matter. The effect of specifying multiple entries with the same key is undefined.

Example:

<map>

  <!-- plugin key with string value -->
  <entry>
    <string>key_one</string>
    <string>Lots Of Copies Keep Stuff Safe</string>
  </entry>

  <!-- plugin key with integer value -->
  <entry>
    <string>key_two</string>
    <int>3000</int>
  </entry>

  <!-- plugin key with long integer value (e.g. number of milliseconds) -->
  <entry>
    <string>key_three</string>
    <long>1209600000</long>
  </entry>

  <!-- plugin key with list value (e.g. list of strings) -->
  <entry>
    <string>key_four</string>
    <list>
      <string>List item one</string>
      <string>List item two</string>
      <string>List item three</string>
    </list>
  </entry>

  <!-- plugin key with map value (e.g. mapping from string to string) -->
  <entry>
    <string>key_five</string>
    <map>
      <entry>
        <string>subkey1</string>
        <string>subvalue1</string>
      </entry>
      <entry>
        <string>subkey2</string>
        <string>subvalue2</string>
      </entry>
      <entry>
        <string>subkey3</string>
        <string>subvalue3</string>
      </entry>
    </map>
  </entry>

</map>

1.2.1. Plugin Value Types#

Plugin values can be of the following types:

XML Element	Plugin Value Type
`<string>`	String
`<int>`	Integer
`<long>`	Long Integer
`<list>`	List
`<map>`	Map

1.2.1.1. String#

XML Element

<string>

Description

An arbitrary string of characters.

Because the plugin is expressed as XML, some characters in the string must be properly encoded:

& is encoded as &.
< is encoded as <.
> is encoded as >.
Non-printable characters and characters outside the 7-bit ASCII set are encoded with numeric character references [1], either decimal character references (for example é encoded as é or é) or hexadecimal character references (for example é encoded as é or é or é or é).

Examples

<string>This is a string value</string>

<string>Taylor &amp; Francis</string>

<string>Vive la diff&#x00e9;rence !</string>

1.2.1.2. Integer#

XML Element

<int>

Description

An integer value. Represented internally as a 32-bit integer.

Example

<int>1234</int>

1.2.1.3. Long Integer#

XML Element

<long>

Description

A long integer value. Represented internally as a 64-bit integer.

Example

<long>5000000000</long>

1.2.1.4. List#

XML Element

<list>

Description

A <list> elements containing an ordered sequence of values (typically all of the same type).

Example

<!-- list of strings -->
<list>
  <string>Item one</string>
  <string>Item two</string>
  <string>Item three</string>
</list>

1.2.1.5. Map#

XML Element

<map>

Description

A <map> element containing an unordered sequence of map entries expressed as <entry> elements. Each map entry is a key-value pair; the key must be the first child of the <entry> element and must be a String, and the value must be the second child of the <entry> element.

The effect of specifying the same key in more than one map entry is undefined.

Example

<!-- mapping from string to string -->
<map>
  <entry>
    <string>key1</string>
    <string>value1</string>
  </entry>
  <entry>
    <string>key2</string>
    <string>value2</string>
  </entry>
  <entry>
    <string>key3</string>
    <string>value3</string>
  </entry>
</map>

Footnotes