Writing Code for Portico

Although the central concepts involved in the Portico framework are quite simple, there is a lot of information to take in. When sitting down to write some code for Portico, knowing where to get started can be one of the hardest problems to overcome.

This document provides you with a brief list of things you will need to know before writing any Portico code, and points you at the relevant resources. It also provides you with a little kick-start to help you get working like the core Portico developers. The resources you need and the information you need to know depends on what your code is doing.

Common Useful Information
There is some common information you will need to know if you are writing virtually anything non-trivial for Portico. Unless you are simply embedding Portico into your application and plan on interacting with it via the standard HLA interfaces, you will need to have a reasonable understanding of the following:


 * The Commons Messaging Framework: The messaging framework that underpins Portico
 * Portico Architectural Overview: Overview of the Portico framework, and how messages flow around it

Writing Code that Uses Portico
If you are not developing code that is to go directly into the Portico distribution itself, you are generally writing code that "uses" Portico.

Writing plug-ins that are distributed separately from Portico is one example of this. If you are embedding an instance of Portico in your own application, you would also fall into this category. Basically, if you are not modifying the Portico source code directly, you would be considered in this group.

Resources Needed
The developers have attempted to make the process of interfacing with Portico as easy as possible. Making use of Portico means that you only need the Portico Portico jar file on your classpath and you are set. You can find the  file in the   directory of your distribution.

Useful Documentation
The documentation you will need varies depending on what you are trying to do.

One of the most useful documentation resources will be the Portico API Documentation (javadocs).

If you are writing a new communications binding plug-in, you will only be interacting with a small part of the framework. The best place to start for this is Writing Bindings.

If you are writing a plug-in that introduces new message handlers or message types, you will need to have a broader understanding of not just how the Portico framework fits together, but how the standard set of handlers/plug-ins work. In that case, it would be advisable to see the Developer Documentation on the various components and structures inside the LRC, RTI and shared components.

Packaging and Deploying Your Code
If you are writing a plug-in, you should refer to Writing Plugins for information on how to package and deploy your code.

If you are embedding Portico into your application, see the Embedding Portico document.

Writing Code to be Included with Portico
If you are fixing bugs, adding new features or otherwise intend to be working directly with Portico (and modifying Portico code), then you will fall into this category. Generally speaking, the main thing that distinguishes this category from the previous is that here you will roll your own custom version of Portico containing your fixes or enhancements.

Note that plug-in writing can fall into this category. As you can easily build your own versions of Portico, you may find it easier to extend Portico by including your plug-ins in a specialized, custom Portico build. Portico ships pre-configured with a default set of plug-ins, all you would be doing here is adding your fixes or extensions to this group and creating an "enhanced" version of Portico.

Resources Needed
The main resource you will need if your work falls into this "Extending Portico" category is the Source Code itself. Apart from Subversion and Java, everything you need to build, test and package Portico is contained within the Subversion repository, so all you have to do is:

1) Check the code out 2) Build the code

Useful Documentation
While people wishing to extend or alter the behaviour of Portico are well served by an understanding of the main Portico RTI, LRC and shared components, it can be virtually vital for someone fixing bugs or working with the source directly.

As is always the case, the Portico API Documentation will prove to be a useful resource, however, having access to the code will also allow developers to get a much deeper understanding of what it going on "underneath the hood".

Or particular interest to those working directly with the Portico source will be the articles describing the source repository structure and how to use it:


 * Source Code: Where to get the Source
 * Java Build Structure: How the source repository is laid out and how to interact with it (building and testing Portico)
 * Testing Framework: The unit testing framework. How to write, build and run the unit tests

Packaging and Deploying Your Code
If you plan to package your work as a separate plug-in, it is best to refer to the Writing Plugins document. However, if you want to roll your own Portico distribution, complete with your fixes or changes, the Build Structure document will tell you what you need to know. Basically, you'll issue a simple  and get the zip/tar-zip files in the   directory.