SolarNode Development Configuration Guide

This guide assumes you have set up your Eclipse workspace as detailed on SolarNode Development Guide. There are a lot of individual OSGi bundles that make up the SolarNode application. Usually you will not want to work with all available bundles. Here are some general guidelines to understanding how the SolarNode bundles are structured.

Project naming conventions

The SolarNetwork code is divided into many small projects. The majority of these projects are OSGi bundle projects, and have names like net.solarnetwork.node.core, which follow a Java package-like naming convention using periods between domain names. Some projects are not OSGi bundles, and they do not follow the Java package-like naming convention. The projects follow these overall naming conventions:

1. Projects that start with net.solarnetwork.central are SolarNet bundles. For example net.solarnetwork.central.core.
2. Projects that start with net.solarnetwork.node are SolarNode bundles. For example net.solarnetwork.node.core.
3. Projects that start with net.solarnetwork but do not fall into the central or node category are supporting bundles, usually custom-built OSGi bundles of non-OSGi libraries. For example net.solarnetwork.org.rxtx which is an OSGi bundle of the RxTx library.
4. Projects with Java package-like names that start with anything else are supporting bundle fragments that are used to customize or configure 3rd party OSGi bundles. For example org.springframework.osgi.log4j.config.
5. Projects without Java package-like names are not OSGi bundles, but support SolarNetwork development in some way. For example solarnode-osgi-target.

Configuring logging

The org.springframework.osgi.log4j.config project is used to configure the Log4j logging settings you want to use when running the application. You need to copy the example/log4j.properties into the root of the project, and make changes to that copy in order to configure the logging.

Configuring solarnode.xml

Some bundles rely on some external XML configuration provided by a file you must create in the solarnetwork-osgi-target project, within a directory named conf. You must create the conf folder and create a new solarnode.xml file within it.

To start, this file should contain a minimum of the following:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:osgi="http://www.springframework.org/schema/osgi"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		http://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/osgi
		http://www.springframework.org/schema/osgi/spring-osgi.xsd">
</beans>

For projects that require solarnode.xml configuration, they will contain an example file located at example/configuration/node.xml within the project. For example, the net.solarnetwork.node.power.sma.sunnynet project contains such an example file. To configure the XML for that project, copy the contents of the node.xml into your /solarnetwork-osgi-target/conf/solarnode.xml file, and then modify solarnode.xml as appropriate.

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 extensions, 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.node.dao.jdbc project exposes some configurable properties as detailed in /net.solarnetwork.node.dao.jdbc/example/configuration/net.solarnetwork.node.dao.jdbc.properties. This bundle configures the JDBC connection used by the SolarNode for persisting data. If you want to customize the JDBC connection in any way, copy this file to /solarnetwork-osgi-target/configurations/services/net.solarnetwork.node.dao.jdbc.cfg and modify it as desired.

Disabling unnecessary projects

The SolarNode code is composed of many individual OSGi bundle projects, many of which you probably don't need or care to work with most of the time. Also, if you checked out all projects from Subversion to start with, you would have checked out many SolarNet projects that you don't need.

You can easily disable those projects by simply closing them in Eclipse. Select the projects you are not interested in using, then choose the Project > Close Project menu. Alternatively you can delete the projects completely by choosing the Edit > Delete menu.

When you are first starting out with SolarNode development, here are some guidelines on disabling projects so you start with just a minimum application to work with:

1. Disable all SolarNet projects -- those with names starting with net.solarnetwork.central.
2. Disable SolarNode projects relating to features you are not interested in. For example the SolarNode application supports features like consumption, power, price, and weather. If you are not interested in a particular feature, disable alll projects whose name starts with that feature. For example to disable the consumption feature you would disable the following projects (this list may be incomplete):
   1. net.solarnetwork.node.consumption
   2. net.solarnetwork.node.consumption.mock
   3. net.solarnetwork.node.consumption.centameter
3. Within a particular feature (such as consumption as described in the previous item) there will be many feature implementation projects that have names starting with the feature project name. Disable all of these implementation projects except for the one named feature.mock. The mock project will provide an implementation of that feature suitable for testing that your environment is set up and running correctly. For example if you want to work with the consumption feature you would disable all consumption projects except net.solarnetwork.node.consumption and net.solarnetwork.node.consumption.mock

To illustrate the idea of SolarNode feature projects, and mock implementation projects, see the following illustration:

SolarNode features have been grouped by colored rectangles, and the mock implementation project for each feature highlighted within each feature.