Neuron Development Guide

Neuron Health is an extension of the open source Tolven Platform. The Tolven Platform is robust and scalable, and the Tolven architecture allows additional features to be added easily through the use of plugins. Neuron Health consists of a set of plugins that add a great deal of functionality to the core Tolven Platform. You too can develop plugins that further extend the functionality of the Neuron Health platform.

To get started developing right away, first make sure you have installed Tolven and have your development environment configured (see [Development Environment Setup]). Then you can create your own plugin following the [Creating a New Plugin] guide. Information about common plugin functions can be found on the [Common Reasons for Creating a Plugin] page.

For more information about the Tolven architecture and plugin structure, continue reading.

Overview

This section is taken from the Tolven Development Guide, a good but outdated resource for developing plugins for the Tolven platform.

This article is intended for those making a change to Tolven that goes beyond configuration. Development may involve web pages, resource bundles, Java code, rules, etc. If you have already configured Tolven, the concept of plugins should not be new to you. Now it is necessary to understand them in a bit more depth.
Almost all of Tolven is made up of plugins: Only a small bootstrap configuration controls which plugins are loaded and executed. If you are building a new Tolven application, the product of the development process will be a plugin.

What is in a plugin

Your project will most likely consist of a single (additional) plugin added to the list of plugins already configured. In essence, a plugin contains all of the little files needed to add some capability to the Tolven environment - all in one place. For example, your plugin might add a wizard page, a drilldown page, perhaps a new validator, maybe some new rules, additions to one or more locale resource bundles. Even a new Java API and implementation.
In most cases, your plugin will make additions to the underlying configuration provided. Here is how this plugin feature works: You will describe an extension to an existing plugin. For example, the tolvenweb plugin has a login page within it that was designed by Tolven. Your plugin manifest can specify that a login page that you define should override the login page provided by Tolven. Likewise, you may add additional pages to the existing tolvenweb application. Technically, these substitutions are made prior to deployment of the EAR file to the application server which means that if you were to look at the running application, it would not contain any page that was overridden by you.
Plugin deployment can seem complex at first. Ant scripts hide most of this complexity, but you still need to understand the basics:
All plugins are zip files and they must contain at least one file called the manifest, which is always named tolven-plugin.xml. This tells TPF how to process your plugin. The manifest will refer to other contents of your plugin typically by directory or file names that are relative to the root of the zip file.

Plugin names

The name of the plugin zip file is significant. <plugin-id>-<version>.zip. The name of the zip file must match the id in the manifest. Likewise, the version scheme is significant. TPF must be able to compare version numbers to determine which is newer. Therefore, the version number must only contain periods (dots) and decimal digits. Version 1.10.1 is greater than, more recent than, version 1.2.0.

Plugin repositories

Plugins reside in plugin repositories. While any number of repositories can be defined, there are three types that you should know about:

• A library repository generally contains plugins that may be used at a particular site. The primary Tolven library is located in the Tolven snapshot you downloaded. Depending on the configuration specified in your tolven-config/plugins.xml file, which is used by tpf -getPlugins. Plugins from this library will be added to the tolven-config/repositoryRuntime repository. You might also think of this as a catalog of plugins.
• The runtime repository, located at tolven-config/repositoryRuntime is the collection of plugins that will be used to assemble and configure your system. In other words, all of the deployment-type commands (configPhase1, configPhase2, etc) and any other explicit plugin command, such as tpf -plugin <plugin name> operates against this repository. So, in this context, runtime means TPF runtime, not necessarily the application server.
• The local plugin repository starts empty in most installations but will be the one that you will use often as a plugin developer: tolven-config/repositoryLocal. This repository can be located anywhere, but we will leave it in the tolven-config directory for this article. The repositoryLocal is scanned at the same time as the main library repository. In other words, it extends the main library with additional plugins. However, repositoryLocal is not an override mechanism. If exactly the same version of the same plugin is found in both repositories, TPF will throw an exception. Therefore, it is important that you increase the version number of a plugin you are updating so that it takes precedence over older plugins with the same id. repositoryLocal is intended to be temporary: A plugin remains in repositoryLocal while it is being tested and is then moved to a library/catalog during the publish process.

Each plugin repository has the same structure: A single file at the top-level named plugin.xml describes the contents of a nested folder named plugins. The plugins folder contains each of the zipped plugins. The top-level plugins.xml file, referred to in this context as repository metadata, must match the contents of the plugins directory. A checksum is computed to detect changes in the plugins directory. This file also contains plugin dependencies.

Two lifecycles to consider

The lifecycle of a plugin project is different from the lifecycle of a plugin zip, the final packaged version of a plugin. The following are some guidelines you should consider:
While a new plugin is initially being developed, the plugin is unpublished. That is, the plugin is not available for download outside of your development environment. It's existence is limited to tolven-config/repositoryLocal, which is sufficient for testing.
At the same time, the plugin project may be committed to CVS/SVN etc. for safe keeping. This generally does not include the plugin zip and does not signify that the official plugin has changed yet, only that someone is working on a new version of the plugin.

Plugin structure (Sections)

A plugin will often contain source, web page, and configuration elements that comprise a functional area. Take allergies for example: client code to load allergies, web pages to display and enter allergies, rules that apply to allergies, etc. So, to make Allergies pluggable, we need to put all (or at least most) of those components related to allergies into a single plugin. Tolven calls its version of this plugin org.tolven.deploy.allergies.
To keep all of the possible parts of a complete plugin organized, and to facilitate refactoring, the plugin manager organizes plugins into several sections. All sections are optional. And you may add sections. In general, a section contains the components that will be directed to a certain system component as described in the table below. Each section in the plugin can contain classes and configuration files appropriate to that section. The project contains a number of section folders. There are two differences between a section folder in your plugin project and the section folder in the plugin:
The project holds class files in the temporary build folder whereas the plugin zip has the classes stored in the section.
Sources in the plugin project are stored in the section while in the plugin zip, sources are stored in an embedded devLib.jar.
The following table shows what the section folders of a complete plugin project might look like.

Section	Components	Description
manifest	tolven-plugin.xml, tolven-plugin-fragment.xml, license file	Defines the plugin as a whole. This directory is copied to the top-level in the finished plugin zip file.
app	applications, trim, etc	Application configuration files. These include application metatdata (xxx.application.xml), core trims, etc.
tpf	source, voc, etc	Components that apply to and run at configuration time. In other words, these classes may be loaded and used when the tpf command is run.
ejb	source, orm	Components added to the tolvenEJB environment that share an entityManager with Tolven. At assembly time, the class files associated with this section will be loaded into appropriate places in the tolvenEJB.jar file, which will then be added to the tolven.ear. This code does not run in the tpf itself.
web	source, web/ajax, web/five, web/drilldown, web/wizard, etc.	Components added to the tolvenWEB war file which is included in the tolven.ear file. At assembly time, the class files associated with this section will be loaded into appropriate places in the tolvenWEB.war file, which will then be added to the tolven.ear. This code does not run in the tpf itself.

Reminder: You don't have to use this structure. It is just a guideline supported by the build scripts in the plugin manager plugin project. The contents of the plugin manifest, manifest/tolven-plugin.xml, must correspond to your plugin structure. In fact, the template includes all of these sections, but most are commented.

Where to go from here

The following links will take you to more detailed articles describing important aspects of development in Neuron:

[Development Environment Setup]
[Creating a New Plugin]
[Common Reasons for Creating a Plugin]