========================================================================
Introduction
========================================================================

This package contains a sample resource locator plugin for Pulse 2.5.
The plugin locates Python installations on Mac OSX (other platforms
may be added in the future).

========================================================================
Contents
========================================================================

The layout of this package is as follows:

README             - this file
build.xml          - a simple Ant build file
.classpath         - an Eclipse classpath file for the plugin project
etc/               - contains third-party dependencies required by the
                     build
ivysettings.xml    - contains settings for Ivy (used in the build)
ivy.xml            - defines the Ivy details of the plugin
.project           - an Eclipse project for developing the plugin
src/
  java/            - Java source code for the plugin
  resources/       - extra source files used to define plugin
                     information
  test/            - a small set of tests for the plugin, illustrating
                     how to use built-in support for JUnit test cases

========================================================================
Building
========================================================================

To build the plugin as-is, you will require Apache Ant 1.7 or later.
Building from scratch requires two steps:

$ ant refresh.lib

This target uses Ivy to download the plugin dependencies from
zutubi.com and puts them in a lib/ subdirectory.  This step has been
kept separate as it will usually only need to be done once.

$ ant package

This compiles the plugin, copies the resources and packages it all up
in:

build/com.zutubi.pulse.core.resourcelocators.python.jar

a complete Pulse 2.5 plugin.  The plugin can be installed via the
Pulse administration UI (see below).

For information on other Ant targets, run "ant -p".

========================================================================
Installing
========================================================================

To install the plugin, go to the administration > plugins page of your
Pulse server, scroll to the bottom of the table and click "install new
plugin".  Then browse to the plugin file and upload it to the master.

To uninstall the plugin, use the corresponding "uninstall" link in the
plugins table.  Note that currently plugins cannot be uninstalled
immediately - the plugin will remain in the "uninstalling" state until
your Pulse server is restarted.

------------------------------------------------------------------------
Installing on Agents
------------------------------------------------------------------------

Since version 2.3 Pulse automatically synchronises plugins installed on
the master to agents.  So no extra step is required to install on
agents.  Note, however, that this is based on changing the plugin
version number, so during the development cycle (when you may not be
changing the version) updates to the plugin will not make it to agents.
For this reason (among others), we recommend developing using a single
local master installation, and ony deplying properly version plugins to
setups involving multiple agents.

------------------------------------------------------------------------
Reinstalling
------------------------------------------------------------------------

If you are regular uninstalling/installing a plugin (likely during
development), the fastest current way to do so is to:

1) Shut down Pulse.
2) Replace the plugin jar file in $PULSE_DATA/plugins with the new
version.
3) Start Pulse.

Pulse will automatically pick up the new version when you start.

If your plugin gets stuck in a bad state (usually caused by manifest or
related errors), first fix the underlying issue in your plugin, then
when installing your new jar also delete the file:

$PULSE_DATA/plugins/plugin-registry.xml

before restarting Pulse.  This clears all existing plugin errors.

========================================================================
Developing
========================================================================

To develop the plugin, consider making use of the package Eclipse
project files, created with Eclipse 3.7.  These give an idea of how to
set up the project to build in an IDE.

Note that the Eclipse project links the JavaDoc documentation to the
relevant jar files, which is very useful.  You can hover over class and
method names to call up the documentation.

------------------------------------------------------------------------
Source Files
------------------------------------------------------------------------

PythonResourceLocator.java:
The main plugin class, this implements the resource location by
implementing the interface provided in Pulse.

PythonResourceLocatorTest.java:
A simple test case for the locator.

------------------------------------------------------------------------
Other Files
------------------------------------------------------------------------

If you would like to change details of the plugin itself, rather than
just make incremental improvements, you may need to edit the following
files:

ivy.xml:
Defines the name of the plugin, and its dependency on Pulse.

src/resources/META-INF/MANIFEST.MF:
An OSGi manifest file - declares details such as the plugin name,
description and the Pulse plugin it depends on.

src/resources/plugin.xml:
Defines the extension points that the plugin "plugs into".

src/java/...:
Contains the actual plugin source code.

========================================================================
Further Help
========================================================================

For further assistance with plugin development, don't hesitate to
contact us at:

support@zutubi.com

or via our forums:

http://forums.zutubi.com/viewforum.php?f=8

Happy plugging-in!