module-tools module

Pnuts User's Guide -> extensions -> module-tools module

Publishing and Sharing Pnuts Modules

Overview
File Format
Internationalization of Module Descriptors
Merged Module Descriptors

Overview

Module descriptor file defines essential information of a module such as module's name, module's version, and URL of JAR files of the module. Module descriptor files are usually used as static Web contents, as well as related resources that are linked from the module description.

module-tools module allows you to access module descriptor files, browse published/installed modules, and install/update modules.

Minimum module descriptor file

<?xml version="1.0" encoding="utf-8"?>
<module-set>
  <module>
    <module-name>sample</module-name>
    <module-version>1.1</module-version>
    <description>sample module</description>
    <resource>
      <name>sample module</name>
      <jar-file>sample.jar</jar-file>
    </resource>
  </module>
</module-set>

File Format of Module Descriptors

Module Descriptor is a XML file that contains a module-set element or a module element.

module-set element

Attribute	Description	Mandatory/Optional
resource-bundle	URL of a resource bundle JAR	Optional

Tag Description Mandatory/Optional

module-ref URL of module descriptor file (must contains a module element) Optional

module module element Optional

module-set-ref URL of other module-set file (must contains a module-set element) Optional

Tag	Description	Mandatory/Optional
module-ref	URL of module descriptor file (must contains a module element)	Optional
module	module element	Optional
module-set-ref	URL of other module-set file (must contains a module-set element)	Optional

module element

Attribute	Description	Mandatory/Optional
location	Original location of the module description file. The value is used as the base of all ralative-URLs in the module element. If not specified, the base URL is where the module descriptor file is located.	Optional
resource-bundle	URL of a resource bundle JAR. If not specified, `resource-bundle` attribute of module-set element is used.	Optional

Tag Description Mandatory/Optional

module-name Module Name Mandatory

module-version Module Version (e.g. 1.0, 1.0.1) Mandatory

description Brief Description Mandatory

last-modified Last modified time (the number of milliseconds since January 1, 1970, 00:00:00 GMT) Optional

comment Comments Optional

pnuts-version Compatible Pnuts version (minimum number) Optional(1.0 by default)

java-version Java version (minimum number) Optional(1.2 by default)

document-url URL of the document page Optional

reference-url URL of a file that contains refererence element Optional

distribution an element that specifies distribution files Optional

resource an elemnt that specifies files of the module Optional

author an element that specifies author Optional

contact an element that specifies contact persons Optional

category an element that specifies keywords that characterize the module Optional

sub-module an element that specifies sub-modules Optional

dependency an element that specifies dependency Optional

Tag	Description	Mandatory/Optional
module-name	Module Name	Mandatory
module-version	Module Version (e.g. 1.0, 1.0.1)	Mandatory
description	Brief Description	Mandatory
last-modified	Last modified time (the number of milliseconds since January 1, 1970, 00:00:00 GMT)	Optional
comment	Comments	Optional
pnuts-version	Compatible Pnuts version (minimum number)	Optional(1.0 by default)
java-version	Java version (minimum number)	Optional(1.2 by default)
document-url	URL of the document page	Optional
reference-url	URL of a file that contains refererence element	Optional
distribution	an element that specifies distribution files	Optional
resource	an elemnt that specifies files of the module	Optional
author	an element that specifies author	Optional
contact	an element that specifies contact persons	Optional
category	an element that specifies keywords that characterize the module	Optional
sub-module	an element that specifies sub-modules	Optional
dependency	an element that specifies dependency	Optional

resource element

Tag	Description	Mandatory/Optional
name	resource name	Optional
license	an element that specifies license term	Optional
jar-file	JAR files, which should be installed in ${pnuts.home}/modules/	Optional
native-lib	native library files	Optional

native-lib element

Attribute	Description	Mandatory/Optional
os	OS (e.g. windows, macosx, solaris, linux, etc.)	Mandatory
arch	hardware architecture(e.g. x86, powerpc, solaris, etc.)	Mandatory

license element

Tag	Description	Mandatory/Optional
license-name	license name (e.g. LGPL)	Optional
license-url	URL of license term	Optional

distribution element

Tag	Description	Mandatory/Optional
file	URL of distribution file	Mandatory

author element

Tag	Description	Mandatory/Optional
name	Author's name	Optional
email	Author's email address	Optional

contact element

Tag	Description	Mandatory/Optional
name	Contact person's name	Optional
email	Contact person's email address	Optional

category element

Tag	Description	Mandatory/Optional
keyword	keywords that characterize the module	Optional

sub-module element

Tag	Description	Mandatory/Optional
module-name	sub-module's name	Optional

dependency element

Tag	Description	Mandatory/Optional
module-ref	URLs of module descriptor files that the module depends on	Optional

reference element

Tag	Description	Mandatory/Optional
function	an element that specifies location of specified function	Optional

function element

Attribute	Description	Mandatory/Optional
name	the name of the function	Mandatory

Internationalizing Module Descriptor

Module descriptor file syntax provides a way to use internationalized resource. The pattern ${keyword} is expanded when module descriptor file is parsed. resource-bundle attribute of module element specifies a JAR file of an international resource bundle.

e.g.

<?xml version="1.0" encoding="utf-8"?>
<module-set>
  <module resource-bundle="properties.jar">
    <module-name>sample</module-name>
    <module-version>1.1</module-version>
    <description>${description}</description>
    <resource>
      <name>sample module</name>
      <jar-file>sample.jar</jar-file>
    </resource>
  </module>
</module-set>

module.properties in properties.jar

description=sample module

Merging Module Descriptors

Module descriptor files can have references to other module descriptor files on different Web servers. The more module descriptor files it links to, the longer it will take to get all information, because of network traffic overhead. merge_module_descriptors() allows you to perpare a merged module descriptor file, so that users can get all module information faster.