======Writing Extension Modules======

Extension module are simple create and register with xmlsh. An Extension modules consists of three components
- A .jar file containing the extension module runtime compiled java.
- A module.xml file describing the extension module
- Optionally a set of dependent .jar files

Once created the module can be deployed so that it is importable using the [[CommandImport import]] command.


=====Creating the extension module code=====
An extension module consists of one or more Commands or functions and optionally the corresponding help document.
Commands and functions may be in any package. Only a single package is exposed via the module.xml file so you should put all commands and functions in one package, then optionally any helper code in additional packages.

An extension module command can be either compiled java, or a xmlsh script. Scripts are any resource in the package which end in ".xsh".
Compiled java commands or functions are classes which derive from org.xmlsh.core.XCommand (for commands) or implements the interface ""org.xmlsh.core.IFunction"" for functions. You may derive from the abstract class ""org.xmlsh.core.BuiltinFunctionCommand"" instead of creating your own base class for functions.

For functions and commands, the classname is the name of the command or function. This has some restrictions on what you can name commands or functions (they must be valid java class identifiers). For example to expose the command "hello" you would create a class named "hello", derived from XCommand and put it in the package described in the module.xml


====Example Command====
Here is an example of a command. This is the exact source code for the "xpwd" command which could be placed in an extension module.

%%(java)

package org.xmlsh.commands.internal;

import java.util.List;

import javax.xml.stream.XMLStreamWriter;

import org.xmlsh.core.Options;
import org.xmlsh.core.OutputPort;
import org.xmlsh.core.XCommand;
import org.xmlsh.core.XValue;
import org.xmlsh.sh.shell.SerializeOpts;
import org.xmlsh.types.XFile;


public class xpwd extends XCommand
{

public int run( List<XValue> args ) throws Exception
{
Options opts = new Options( SerializeOpts.getOptionDefs() );
opts.parse(args);
// args = opts.getRemainingArgs();

XFile file = new XFile(getCurdir());


OutputPort stdout = getStdout();
SerializeOpts serializeOpts = getSerializeOpts(opts);
XMLStreamWriter writer = stdout.asXMLStreamWriter(serializeOpts);

writer.writeStartDocument();

file.serialize(writer,false,false);

writer.writeEndDocument();
writer.close();

stdout.writeSequenceTerminator(serializeOpts);

return 0;

}
}
%%

======Creating the module.xml======

To describe the extension module you must supply a module.xml file. This file coresponds to the module schema.
An example of a module.xml file from the MarkLogic extension module is as follows
%%(xml)
<module
module_version="10"
name="marklogic"
package="org.xmlsh.marklogic"
require="1.1.2"
>
<classpath>
<file url="marklogic_ext.jar"/>
<file url="xcc.jar"/>
</classpath>
</module>
%%


============