SolarNet Development Guide

SolarNet Development Guide

This guide explains how to setup a development environment for contributing or modifying the SolarNet application code.

The SolarNet project consists of a set of OSGi bundle projects that, when combined and run in an OSGi container, form a complete SolarNet application. Each OSGi bundle comes configured as an Eclipse IDE plug-in project (Eclipse refers to OSGi bundles as "plug-ins" and its OSGi development tools are collectively known as PDE). Although Eclipse is not actually required, the remainder of this guide will describe setting up Eclipse for viewing and running the code for development purposes.

Eclipse Setup

If you haven't already set up your SolarNetwork development environment, go through the Eclipse Setup Guide first, and then return here.

Clone Git repositories

The SolarNet project is contained in the solarnetwork-central repository. You can clone a Git repository by going to Window > Open Perspective > Git Repository Exploring (you may need to choose "Other..." under Open Perspective if Git does not appear there).

1. [email protected]:SolarNetwork/solarnetwork-central.git

Note this is in addition to the common repositories mentioned in the Eclipse Setup Guide, which also describes in more detail how to clone repositories in Eclipse.

Bundle project naming conventions

The SolarNet code is divided into many small projects which follow a Java package-like naming convention using periods between domain names, like net.solarnetwork.central.datum. All SolarNet-specific projects start with new.solarnetwork.central followed by a feature name and then optionally followed by other implementation specific names. Examples of features are:

• in - net.solarnetwork.central.in.* - the SolarIn app
• query - net.solarnetwork.central.query.* - the SolarQuery app
• user - net.solarnetwork.central.user.* - the SolarUser app

If you are not interested in a particular feature, you can disable all projects whose name starts with that feature by closing them in Eclipse (right-click and choose Close Project.

Configuring bundle properties

Some bundles expose properties that can be configured to suit different operating environments. These bundles will always provide default values for the configurable properties, so you only need to create custom properties files if the default values do not match your local environment.

The bundle properties are configured via Java Properties files located in the /solarnetwork-osgi-target/configurations/services directory. If a bundle project exposes configurable properties, it will have an example properties file in the example/configuration directory within that project. These files will have particular names which must not be changed because the bundle will look for its properties file based on the pre-defined name. To customize the properties for a bundle, copy the desired example/configuration/*.properties file into /solarnetwork-osgi-target/configurations/services, rename it to have a .cfg extension, and then modify the copied file as necessary. The example files will contain all available configurable properties, along with documentation on each property.

For example, the net.solarnetwork.central.in.biz project exposes some configurable properties as detailed in /net.solarnetwork.central.in.biz/example/configuration/net.solarnetwork.central.in.properties. This bundle configures the SolarIn identity information used by the SolarNet for accepting data from SolarNodes. If you want to customize these details in any way, copy this file to /solarnetwork-osgi-target/configurations/services/net.solarnetwork.central.in.cfg and modify it as desired.

Database setup

SolarNet requires a PostgreSQL database, version 9.3 or higher, to operate. Please note that only version 9.3 has been extensively tested. It also requires the plv8 extension and a related configuration setting added to postgresql.conf:

	plv8.start_proc = 'plv8_startup'

There are SQL setup scripts to create the initial database tables located in the net.solarnetwork.central.datum project, in the defs/sql/postgres directory. The postgres-init-plv8.sql script is designed to be run by the psql utility and create the necessary plv8 shared global functions. The postgres-init.sql script is designed to be run by the psql utility and create all other necessary database tables, functions, and indices used by SolarNet. For example, to create a new solarnetwork user, new solarnetwork database, and initialize all the necessary structures, you could do the following steps (assuming you've configured the plv8.start_proc property as shown previously):

createuser -ADEP solarnetwork
createdb -E UNICODE -O solarnetwork solarnetwork
createlang plv8 solarnetwork 
psql -U solarnetwork -d solarnetwork -f postgres-init-plv8.sql
psql -U solarnetwork -d solarnetwork -f postgres-init.sql

PostgreSQL administration is beyond the scope of this article. Please see the PostgreSQL documentation available online for more information.

plv8 global startup configuration

SolarNet expects some plv8 functions to be available globally, which means they must be added to plv8's installation-wide function configured by the plv8.start_proc database setting in postgresql.conf. As this is shared with all databases in the installation, you might have other global functions defined already. All SolarNet global functions are created within a top-level sn object, e.g.

CREATE OR REPLACE FUNCTION public.plv8_startup()
  RETURNS void 
  LANGUAGE plv8 AS
$BODY$
'use strict';
/**
 * @namespace
 */
this.sn = {
	...
};
...
$BODY$;

You could easily merge the contents of the public.plv8_startup() function defined in postgres-init-plv8.sql into your own startup function, as long as you are not already using a top-level object named sn.

Configure development settings

You need to configure some development settings in the /solarnetwork-osgi-target/configurations/services directory.

File	Description
net.solarnetwork.central.dao.jdbc.cfg	Configure JDBC settings that match your local Postgres server environment. For example: jdbc.driver = org.postgresql.Driver jdbc.url = jdbc:postgresql://localhost:5432/solarnet jdbc.user = solarnet jdbc.pass = solarnet </td> </tr> </tbody>

SolarIn PKI

If you want to support SolarNode development alongside SolarNet development, you'll need to configure the proper TLS support, as described in the Developer PKI guide.

Running or debugging the SolarNet application

See the Debugging SolarNetwork with Eclipse page for information on running SolarNetwork applications within Eclipse.