OSGI is a specification for building modular Java applications. Like many things Java it is based on a specification with multiple implementations. Equinox is the implementation that the Eclipse framework is built upon to provide an extensible IDE. Alternatively, there are other implementations such as Felix and Knopflerfish.

As of 2021, OSGI has been around for quite a while. However, my interest has been piqued over the last year since I’ve been working with Eclipse plugins. When working on Eclipse plugins it always felt like Eclipse is doing a lot of the background work. As a result, I thought I would throw out all the tooling and give it a try from scratch.

The Project

This project is meant as a light introduction to OSGI in which we are going to :

• Create a simple Activator class that is
• Packaged into an OSGI bundle which is then
• Loaded into an OSGI Container and then
• Started and
• Stopped and finally
• Uninstalled

If any of those terms seem strange, I’ll be explaining them as I go. Firstly, a bundle is just a special jar file that contains some additional content in the MANIFEST.MF file. This extra metadata allows OSGI containers to install the bundle, check that all dependencies are available and notify the activator that it has started. The activator is a class that implements the BundleActivator interface and is called when the bundle is started and stopped.

First we will create a directory with our project in:

mkdir osgiTest
cd osgiTest
mkdir -p uk/co/andygibson/osgi/helloworld/
mkdir META-INF
<edit> uk/co/andygibson/osgi/helloworld/Activator.java

Substitute <edit> with the editor (atom, code, gedit, nano, notepad, vim etc) of your choice to edit a new file called Activator.java.

Additionally, you should have the java, jar and javac tools on the command line path to be easily called.

The Source

Once you have the Activator.java file in an editor, add the following code:

package uk.co.andygibson.osgi.helloworld;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {

    public void start(BundleContext context) throws Exception {
        System.out.println("Starting my activator");
    }
    public void stop(BundleContext context) throws Exception {
        System.out.println("Stopping my activator");
    }
}

This is our activator completed. It is called by the OSGI container when our bundle is started and stopped. The activator is referenced from the META-INF/MANIFEST.MF file which we’ll edit next:

Bundle-Bundle-RequiredExecutionEnvironment: JavaSE-1.8	
Bundle-SymbolicName: uk.co.andygibson.osgi.helloworld
Bundle-Bundle-Version: 1.0.0
Bundle-Name: Hello World App
Bundle-ManifestVersion: 2
Bundle-Classpath: .
Bundle-Activator: uk.co.andygibson.osgi.helloworld.Activator
Export-Package: uk.co.andygibson.osgi.helloworld
Import-Package: org.osgi.framework;version=1.3.0

These attributes define our Bundle, the version of java it requires and any dependencies we need and also the location of our activator class.

The Build

We are going to use plain old command line tools to compile our Bundle – I did say it was OSGI by hand. We need to :

• Compile our activator
• Package our activator into a jar file with our MANIFEST.MF

In order to compile, we’ll need a copy of the org.osgi.framework jar dependency. There are a couple of ways of doing this, you can download it from somewhere, or search for a local copy. You might even have one in your local maven repository which is where I got mine. Once you have a copy, you can add it to the following line to compile your activator:

javac -cp org.osgi.framework-1.9.0.jar uk/co/andygibson/osgi/helloworld/Activator.java

Once completed, we have class file in the uk/co/andygibson/osgi/helloworld folder. To jar it up use the jar command to create a jar file containing our class and the MANIFEST.MF file.

jar cvfm uk.co.andygibson.osgi.helloworld.1.0.jar META-INF/MANIFEST.MF uk/co/andygibson/osgi/helloworld/Activator.class 

The Execution

In our directory , we have a jar file that contains our class and the MANIFEST.MF. This is now a bundle which can be loaded into an OSGI container. For this, we will use Felix. Go to the Downloads page and download a zipped version of the the framework. It should be at the top of the page under “Felix Framework Distribution”. Download the zip binary, and unzip it in a folder.

Open a terminal and go to the folder containing Felix and start it by typing:

java -jar bin/felix.jar

You should end up with a felix console that will let you query the OSGI container. Try typing lb:

g! lb
START LEVEL 1
   ID|State      |Level|Name
    0|Active     |    0|System Bundle (7.0.1)|7.0.1
    1|Active     |    1|jansi (1.18.0)|1.18.0
    2|Active     |    1|JLine Bundle (3.13.2)|3.13.2
    3|Active     |    1|Apache Felix Bundle Repository (2.0.10)|2.0.10
    4|Active     |    1|Apache Felix Gogo Command (1.1.2)|1.1.2
    5|Active     |    1|Apache Felix Gogo JLine Shell (1.1.8)|1.1.8
    6|Active     |    1|Apache Felix Gogo Runtime (1.1.4)|1.1.4

Starting the Bundle

Now lets install and start our bundle. In the Felix console, type the following:

g! felix:install /home/andy/dev/projects/osgiTest/uk.co.andygibson.osgi.helloworld.1.0.jar
Bundle ID: 12
g! start 12
Starting my activator

Finally, we’ve installed the bundle, for which we received a bundle id (12). We then used that to start the bundle which caused the activator message to display.

If you type lb again, you will see the similar list of bundles, but our bundle will be included there now:

START LEVEL 1
   ID|State      |Level|Name
    0|Active     |    0|System Bundle (7.0.1)|7.0.1
    1|Active     |    1|jansi (1.18.0)|1.18.0
    2|Active     |    1|JLine Bundle (3.13.2)|3.13.2
    3|Active     |    1|Apache Felix Bundle Repository (2.0.10)|2.0.10
    4|Active     |    1|Apache Felix Gogo Command (1.1.2)|1.1.2
    5|Active     |    1|Apache Felix Gogo JLine Shell (1.1.8)|1.1.8
    6|Active     |    1|Apache Felix Gogo Runtime (1.1.4)|1.1.4
   12|Active     |    1|Hello World App (0.0.0)|0.0.0

If you type felix:stop 12 you will see the close message in the console. This is because it stops our bundle and causes the Activator stop method to be called.

You can start and stop the bundle as many times as you want. Additionally, you can even start and stop Felix and see that the start amd stop activator methods are called when we start and stop the container.

g! exit 0
Stopping my activator
...
...
java -jar bin/felix.jar 
Starting my activator
____________________________
Welcome to Apache Felix Gogo

g!

The Tooling

Without a doubt, its easy to see why we use tooling to create our java apps. This is just a couple of files and is quite a task. Traditional tools like Maven or Gradle use repositories to supply us with dependencies on demand based on the contents of their source files, pom.xml for example.

However, if we were to use maven we would specify our dependencies in the pom file. At the same time, it would mean we need to manually keep dependencies in the MANIFEST.MF file up to date. Unsurprisingly, this is where special tools like Tycho, BND and Eclipse plugin projects come in. They work with the manifest file and use that to provide the list of dependencies (so called Manifest first tools like Tycho or Eclipse). Others can build up the manifest file based on the configuration of the tool (i.e. BND) to build dependencies that way.

We can create a class hierarchy of serializers that makes use of inheritance to replace a set of if/then statements based on the object type. In this post, we’ll implement serializers that are inherited for the different Pet types and ensure that the serialization of each Pet type of encapsulated in its own serializer.

One problem is that the execution of overridden implementations is sequential, we would execute the implementation in the parent class, then the first subclass, and then any further subclasses. Since our top level implementation likely consists of :

• Start writing an object “{“
• Write Object properties “x = 1”
• End writing an object “}”

If we subclass the serializer and override the serialize() method and call the parent implementation, in JSON we will open the object, close it, and then write any subclass properties. We want to open the object, write all of the properties, including subclass properties, and then close the object.

Template Method

We can solve this problem using a template method which is invoked during the execution of an algorithm, and provides options to extend the algorithm while maintaining the main structure of it. This is a good technique to use when you want to maintain a rigid list of actions, but allow one of those actions to be overridden and extended.

We’ll create an ObjectSerializer class that is used as the base class for our serializers. This class expects subclasses to be used to serialize objects.

public abstract class ObjectSerializer<T> extends StdSerializer<T> {

  public ObjectSerializer(final Class<T> t) {
    super(t);
  }

  @Override
  public void serialize(final T value, final JsonGenerator gen, final SerializerProvider provider) throws IOException {
    gen.writeStartObject();
    doWriteProperties(value, gen, provider);
    gen.writeEndObject();
  }

  protected abstract void doWriteProperties(final T value, final JsonGenerator gen, final SerializerProvider provider);
}

Our serialize method starts a new object, invokes the call to write the object properties, and then ends the object. Any properties written in the doWriteProperties method will sit inside the JSON object.

Our PetSerializer won’t write any Pet, but could just write the common properties for the Pet object :

public class PetSerializer<T extends Pet> extends ObjectSerializer<T> {
  public PetSerializer(final Class<T> clazz) {
    super(clazz);
  }

  @Override
  protected void doWriteProperties(final T value, final JsonGenerator gen, final SerializerProvider provider)
      throws IOException {
    // this could go in the subclass serializer if a more calculated value was needed.
    gen.writeStringField("type", value.getClass().getSimpleName());
    gen.writeStringField("name", value.getName());
  }
}

Here we override the doWriteProperties method to write the type and the name, the two common values of the Pet type that need serializing. Note that we also enhanced the generic type to ensure that we only use this on subtypes of Pet.

We can now subclass this serializer for each of our Pet types :

public class DogSerializer extends PetSerializer<Dog> {
  public DogSerializer() {
    super(Dog.class);
  }
  @Override
  protected void doWriteProperties(final Dog value, final JsonGenerator gen, final SerializerProvider provider)
      throws IOException {
    super.doWriteProperties(value, gen, provider);
    gen.writeStringField("size", value.getSize().toString());
  }
}

and

public class SnakeSerializer extends PetSerializer<Snake> {

  public SnakeSerializer() {
    super(Snake.class);
  }

  @Override
  protected void doWriteProperties(final Snake value, final JsonGenerator gen, final SerializerProvider provider)
      throws IOException {
    super.doWriteProperties(value, gen, provider);
    gen.writeNumberField("length", value.getLength());
  }
}

We have implemented the PetSerializer for our two classes and override the doWriteProperties method to write properties specific to that Pet.

To use our new serializers, we just need to register them with the Jackson Module in our main code. Note that we no longer need to register the Pet serializer since it is never used directly, only from their subclasses. We do however have to register the serializers for the Dog and Snake classes.

public class Main {

  public static void main(final String[] args) throws JsonProcessingException {
    final ObjectMapper objectMapper = new ObjectMapper();
    final SimpleModule module = new SimpleModule("mySerializers");
    module.addSerializer(new PersonSerializer());
    module.addSerializer(new DogSerializer());
    module.addSerializer(new SnakeSerializer());
    objectMapper.registerModule(module);
    ...
    ...
  }
}

The rest of the code to create the model and write it to JSON will now still work with the new serializers used to write the objects. While this does get rid of the code smell mentioned originally, technically, it is only moving it to a hidden location. Jackson still does some kind of lookup for the class to determine what serializer it should use instead of a set of if statements to locate the matching serializer.

Most people’s first introduction to Jackson is using the default serializer through reflection and then using annotations or mixins. Annotations can be great but they can clutter code, cause additional dependencies and the more complex your situation, the less likely annotations are going to be enough to meet your needs. This is especially the case when you have to adhere to another JSON schema and don’t want to mirror that schema in your model with annotations.

Serializers are classes which can be used to serialize your objects into JSON. The advantage of these is that you have absolute control over the JSON that is produced. It does this by literally adding each element to the JSON document you are writing.

Benefits of Serializers

If you rely on annotations or even the default reflection serializers, you run the risk of having new fields introduced into your json documents and causing errors elsewhere, especially if it is being consumed by something that is strict about the expected content. Serializers make adding fields a very deliberate task around which you can put tests to ensure you are getting the JSON you expect.

For a little more work, you get complete control over your content and don’t have to worry about the limitations of annotations which sooner or later, in any larger project will pay off. By incorporating good design practices you can also construct a rich set of serializers that makes extending them easy.

The source code for the sample project is available on the blog post code repository Let’s look at a simple model for our serializer:

Let’s look at a simple model for our serializer:

class Person {
  private String firstName;
  private String lastName;
  private List<Pet> pets;
}

class Pet {
  private String name;
}

class Dog extends Pet {
  public enum Size {SMALL, MEDIUM, LARGE};
  private Size size;
}

class Snake extends Pet {
  private int length;
}
//getters/setters and convenience methods ommitted.

Each person has a list of pets which can be of different types. Polymorphism is often a problem when writing JSON because the JSON itself doesn’t indicate the type of the object being written. You can ask Jackson to persist a field to indicate the type so it can be deserialized later on. However, if you are dealing with a custom schema, that may not be an option, or the type may be based on some other logic.

We extend StdSerializer and implement the single method serialize. We also create an empty constructor which calls the super constructor with the class of object we are serializing.

We’ll start with our Person first and we’ll start by writing out our fields.

PersonSerializer.java:

public class PersonSerializer extends StdSerializer<Person> {

  protected PersonSerializer() {
    super(Person.class);
  }

  @Override
  public void serialize(final Person value, final JsonGenerator gen, final SerializerProvider provider)
      throws IOException {
    gen.writeStartObject();
    //write string field and field name in one method
    gen.writeStringField("firstName", value.getFirstName());
    gen.writeStringField("lastName", value.getLastName());
    //write the field name and then the value
    gen.writeFieldName("pets");
    gen.writeObject(value.getPets());
    gen.writeEndObject();
  }
}

When persisting the object, we use methods on the JsonGenerator to create content. We start by indicating we want to start a new object, and then we write our fields manually. When we call writeObject to write our pets, we pass in the object and Jackson will figure out how to serialize it. Finally, we call the method end our pet object .

Jackson will try and persist the Pet as a simple object using reflection to pull the properties and write them. This is alright if you don’t care about the final schema and you aren’t worrying about reading the JSON back in. Ideally, we want another serializer to write the Pet class taking into account all the different Pet subclass types.

Now lets look at serializing our Pet. We could write one serializer per concrete type, but we have the option of writing just a common PetSerializer class and all subclasses will use that serializer

For the pet, we want to write a value to indicate the type of Pet we are writing. We will make it the same as the simple class name for now. We then write the Pet fields and then fields that are specific to subclasses. One great thing about serializers is that you can utilise inheritance to make reusable serializers, or use composition to invoke another type serializer as needed.

public class PetSerializer extends StdSerializer<Pet> {

  public PetSerializer() {
    super(Pet.class);
  }

  @Override
  public void serialize(final Pet value, final JsonGenerator gen, final SerializerProvider provider)
      throws IOException {
    gen.writeStartObject();

    gen.writeStringField("type", value.getClass().getSimpleName());
    gen.writeStringField("name", value.getName());

    if (value instanceof Snake) {
      gen.writeNumberField("length", ((Snake) value).getLength());
    }
    if (value instanceof Dog) {
      gen.writeStringField("size", ((Dog) value).getSize().toString());
    }
    gen.writeEndObject();
  }
}

Putting It Together

To test this, we need to construct a Jackson ObjectMapper instance and add these serializers to it using a module. We can then use the object mapper to save any combination of Person and Pet instances and collections. Once registered, Jackson will use the serializer anytime it encounters an object of that type.

  public static void main(final String[] args) throws JsonProcessingException {
  public static void main(final String[] args) throws JsonProcessingException {
    //you can create this once and re-use it everywhere
    final ObjectMapper objectMapper = new ObjectMapper();
    final SimpleModule module = new SimpleModule("mySerializers");
    module.addSerializer(new PersonSerializer());
    module.addSerializer(new PetSerializer());
    objectMapper.registerModule(module);

    // build our models
    final Person p1 = ...
    final Person p2 = ...

    final Collection<Person> people = new ArrayList<>();
    people.add(p1);
    people.add(p2);

    // now write the json
    System.out.println("people unformatted is:\n" + objectMapper.writeValueAsString(people));

    // grab the pretty printer and store it
    final ObjectWriter prettyWriter = objectMapper.writerWithDefaultPrettyPrinter();

    // now write formatted json
    System.out.println("people are :\n" + prettyWriter.writeValueAsString(people));
    System.out.println("p1 is :\n" + prettyWriter.writeValueAsString(p1));
    System.out.println("p2 is :\n" + prettyWriter.writeValueAsString(p2));
    System.out.println("p2.pet(0) is :\n" + prettyWriter.writeValueAsString(p2.getPets().get(0)));
  }
}

Here we have Jackson write a collection of people, and individual Person, or an individual Pet and it will use the serializer. We also switch between using the pretty printer for displayable json, and the default writer which removes formatting and condenses the content.

Additional Thoughts

We technically, could/should put try/except blocks around the object/array start/end blocks like so :

gen.writeStartObject();
try {
  ...write properties to JSON...
} finally {
  gen.writeEndObject();
}

This is so we will always put the enclosing brace ‘}’ on our JSON object in the event that an exception is thrown while generating the content. Problem is that as soon as the exception is thrown, then you won’t write any more of the object to the document, and you could end up with a partial document and no exception thrown. For that reason, I think its better to throw the exception and terminate generating the document. However, your mileage may vary.

Serialize the object without context

When creating a serializer, you have to implement it is as a way of serializing the object only. Assume it knows nothing about the context it is being written in, whether its a ‘pet’ property, an array or a single item. For example, our PetSerializer writes the value for a single pet wrapped in a json object. Don’t assume it is being written as a pet property of another class and write the property name. Leave it to the invoking class to handle any content around the object being written. The PersonSerializer writes the “pets” field name then passes in the collection to be written. Jackson takes responsibility for writing the array start/end brackets of the collection and defers to the PetSerializer to write the Pet content. By doing this, you create serializers that are consistent and reusable. Don’t write serializers for collections of objects, just the object itself.

The current trends are to write code or scripts that are whisked away into the cloud to be interpreted or executed remotely on a garbage collected virtual machine, often through virtual containers on some kind of virtual computing instance.

For me, computing has always been personal, writing code that runs on a box that sits on, or below your desk. Writing something in C++ takes me back to those times, and reminds me of the metal that all our code runs on eventually.

It’s like taking a stroll through woodlands and getting back to basics, while taking a break from the city.

Don’t get me wrong, all those high level abstractions have their place and purpose, especially when considering some of the gotchas of C++, but sometimes its nice to pack a bag, and go camp in the woods. It may be difficult, but it’s a pleasant challenge.

Coming from a Java background, we are pretty lucky that Java has had multiple build tools that can help manage Java projects such as organising class and test sources, handling dependencies, running tests and so on. It was not always this way, originally, there were IDE specific builders that put the source in their own structures and knew how to build them. This was problematic if you wanted to build outside of the IDE, and wouldn’t work in today’s world of continuous integration. Ant came along and let us write build scripts that could take source code of any structure and produce class, source and javadoc jar files for them, and IDEs could take advantage of such scripts.

With Maven, and later Gradle, we were able to create projects with a predefined structure that could be compiled easily just adding a class or test class file in a specific directory. IDEs were able to provide plugins to support these frameworks creating a fairly rich environment where it is easy to get started with Java.

With C++ (and of course plain old C), we don’t have the same solutions, historically, tools like Make have provided Ant-like build systems where you can put your source code where you like and write a script to find and build it. C++ has many more options with regards to compilation for things like build types (Release, Debug etc), linking dynamic & static libs and the target platform to name a few. Some of this complexity was been wrapped up in a tool called CMake which is a higher level abstraction of the build process. Technically, its not a build system, it creates a configuration from which the project can be built.

So I wanted to come up with a basic template for a C++ project that can be built with CMake, and used as the basis for other projects. I wanted to be able to compile and run from the command line and also be able to run from an IDE such as Eclipse and/or KDevelop. I also wanted it to be structured such that it wasn’t overly verbose for small projects but flexible enough that I can expand it later on and refactor as needed. Longer term I want to add testing in, but we’ll start without for now.

I went for a container project which contains sub projects for the main application, and a static linked library. The library could always be spun out as a dynamic library and moved into its own project.

Sample Project

Our project will have the following directory structure:

Sample Project
     |
     | -- calcApp
     |
     | -- calcLib

CMake works by having CMakeLists.txt files in each folder of the project and sub projects. In the top level folder we put a CMakeLists.txt file that is for the project, and it includes the two subdirectories below it. CMake will drill down, find the CMakeLists.txt file in the subdirectories and build elements in those folders.

cmake_minimum_required(VERSION 3.5)

project(someProject)

add_subdirectory(calcLib)
add_subdirectory(calcApp)

The first line defines the minimum version of CMake required to build this project. The project() definition defines the project name. We then add the two subdirectories for our sub-projects.

calcLib

Our next step is to implement the calcLib and set up the CMake files for it. We will have a simple Calc class that just has a couple of methods.

C++ often has header files and source files separately, the header defines the interface to a method or class while the source implements it. Our header will go in the include directory of the lib, and goes in a subdirectory so we can make include file names more unique. The following is the content of calcLib/include/calc:

#ifndef CALCLIB_INCLUDE_CALC_CALC_H_
#define CALCLIB_INCLUDE_CALC_CALC_H_

class Calc {
public:
	int add(int a,int b);
	int sub(int a,int b);
};

#endif /* CALCLIB_INCLUDE_CALC_CALC_H_ */

We can create an implementation of this in the calcLib/src/Calc.cpp file:

#include "calc/Calc.h"

int Calc::add(int a, int b) {
	return a+b;
}

int Calc::sub(int a, int b) {
	return a-b;
}

We include our header file, and then proceed to complete the implementations of the interface defined in the header file. Note that we prefix our header file with calc from the calc subdirectory in our include directory.

Our last piece for the lib is the calcLib/CMakeLists.txt:

add_library(calcLib src/Calc.cpp)

message("CalcLib current source dir = ${CMAKE_CURRENT_SOURCE_DIR}")

target_include_directories( calcLib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)

Since C++ lets us build executables or libraries we need to tell CMake what we want our target to be. add_library is used to define a library target, give it a name, and define the source files for it. In this case, we are creating a library called calcLib and adding our src/Calc.cpp source file.

The message command is used to log messages back to the user. CMake internal or user defined variables can be used inside the string to log them as part of the message. This isn’t needed, I just included to show you how to create output.

target_include_directories is used to define the include directory for this lib. Note that we use the target name calcLib to attach the include directory to the target. Because of the nature of C++ with regards to libraries and linking there are a few options on this command to define the visibility of the includes. We have defined ours as PUBLIC for now.

calcApp

Now we have our library all completed, we can work on our main app in the calcApp directory. This is a simple main.cpp class which prints a message and invokes our calculator to show it is all hooked up.

calcApp/main.cpp:

#include <iostream>
#include "calc/Calc.h"

int main() {
	Calc calc;
	std::cout << "Hello World 12+7 = " << calc.add(12,7) << "\n";
}

Pretty simple stuff. We need to also add a CMakeLists.txt file which will define the executable and pull in our library.

calcApp/CMakeLists.txt

add_executable(calcApp main.cpp)

target_link_libraries(calcApp calcLib)

add_executable is like add_library, it lets us define an executable we want to create, gives it a target name and lets us specify the source files to be added to it.

target_link_libraries lets us link our library into the executable when it gets built. In this case we are doing a static link and the library will be pulled into the executable.

Building It All

That should be everything, and we should be able to build and run our app. You can build the project by opening a command line, going to the project root folder and typing:

mkdir build
cd build
cmake ..
make

That should build the project for you, and you can run the executable from calcApp/calApp

That about wraps it up, you can get the source code from my blog post code git repository under cmake-basic.

There are a lot of knobs to play with with regards to building C++ projects, and how they are structured. With Java, while we have the option of adding jars to executables at runtime through the class path, its often the case that we just build a jar containing all the code we need. Similarly, we could bind java libraries at run time, but often choose not to. With C++ here we have a basic outline of a project that should cover simple cases.

Next I’m going to be looking at incorporating a test framework to give us a real base project to work with.

We are going to start with a HeightProvider class that is used to provide us with heights of the terrain at a given point. Now, bear in mind we are aiming to ultimately have an infinite terrain to fly over, so we want our HeightProvider to account for that.

In is simplest form, the HeightProvider is an interface that has one method.

public interface HeightProvider {

  public float getHeight(float x, float y);
}

A quick note here, I am using floats as that is the preferred type for JME, most likely since that is the preferred type of OpenGL.

So for this code, I’m going to create some little util methods on the interface so we can chain the implementations and create some useful features.

public interface HeightProvider {

  /**
   * Return the height of the map at a given x,y point.
   */
  public float getHeight(float x, float y);

  /**
   * Scale out the x,y co-ords, i.e. spread the map out further
   */
  public default HeightProvider scale(float scale) {
    return (x, y) -> this.getHeight(x * scale, y * scale);
  }

  /**
   * Multiply the height so we get taller points 
   */
  public default HeightProvider mul(float mul) {
    return (x, y) -> this.getHeight(x, y) * mul;
  }

  /**
   * Create a height provider based on the JME noise functions.
   */
  public static HeightProvider noise() {
    return (x, y) -> ImprovedNoise.noise(x, y, 87);
  }
}

This gives us a HeightProvider instance on which we can call the getHeight() method repeatedly and we should get the same value back. This is essential. We aren’t just returning random numbers, we are generating some pseudo random numbers, usually based on noise.

JME comes with some classes to help with specifying terrain using height map and terrain classes. You can see more about them here. We will use the TerrainQuad class for now to help us get up and running.

We’re going to add one more method to our HeightProvider to get it to produce an array of float heights for our map. This will allow us to use our HeightProvider to generate he values for the TerrainQuad.

public interface HeightProvider {
...
  public default float[] toFloats(float x, float y, int size) {
    final float[] heightData = new float[size * size];
    for (int ix = 0; ix < size; ix++) {
      for (int iy = 0; iy < size; iy++) {
        heightData[(ix * size) + iy] = getHeight(x + ix, y + iy);
      }
    }
    return heightData;
  }
...
}

We are assuming a square terrain tile is being used. The x and y coordinates that we pass in indicate the start point of the tile. Remember, this terrain could go on for miles. We plug this coordinate into the height provider to give us a height for that point which we store in the array.

Now we have our height provider in place, lets add some code to our main class to use it!

From our first example, we will keep our code to move the camera, add the light, and create the material. We will change the code to create the geometry and we may tweak the position of the camera a bit:

  private static final int MAP_SIZE = 513;
  private static final int TILE_SIZE = 65;

  @Override
  public void simpleInitApp() {

    // set how fast WASD keys move us over the landscape.
    flyCam.setMoveSpeed(10);

    // move up, to the side and look at the origin
    getCamera().setLocation(new Vector3f(0, 12, 30));
    getCamera().lookAt(Vector3f.ZERO, Vector3f.UNIT_Y);

    // lets put some light in
    final DirectionalLight sun = new DirectionalLight(new Vector3f(0.2f, -0.6f, -0.5f).normalize());
    sun.setColor(ColorRGBA.White);
    rootNode.addLight(sun);

    final Material mat = new Material(assetManager, "Common/MatDefs/Light/Lighting.j3md");
}

So far so good, not too much different from before. Since we might have some hills, the camera has been moved up a bit, and pushed back through the screen so when we look at the origin we aren’t looking straight down. We also set the fly cam speed so we can move through our scene at a fairly fast pace.

Now to add the geometry. We want to create a new TerrainQuad and assign it the float values from our height provider. For now we will keep it simple and not worry about tiling and LOD. I’ve added a couple of constants at the top to indicate the tile size and heightmap size we are using. These must be (2^n)+1 values (9,17,33,65,129,257,513) with the tile size usually being less. Again, JME docs on the TerrainQuad can tell you all about that. On to the code!

    final HeightProvider provider = HeightProvider.noise();
    final float[] data = provider.toFloats(0, 0, MAP_SIZE);
    final TerrainQuad q = new TerrainQuad("terrain", TILE_SIZE, MAP_SIZE, data);

If you run this now, you are probably going to be pretty disappointed. No rolling hills and sweeping valleys, it just looks like the plains of Hoth:

So whats going on here, then. Well, 2 things are wrong with this. Our height provider is asked for values on integer steps, coordinates are requested of the form (0,0), (0,1), (0,2)….(1,0), (1,1), (1,2).

For this implementation, and I believe every Perlin Noise implementation, at the integer boundaries, the value is always zero. The other problem is that noise returns small values between -1 and 1 which is a really small height in our landscape.

However, those nice helper functions can fix this for us. We want to take our provider, then scale down the co-ordinates so rather than range from 0-513, they range from 0 a smaller number with interpolations in between. Change the provider constructor to the following:

final HeightProvider provider = HeightProvider.noise().scale(0.2f).mul(10);

This creates our noise provider, and then the scale method creates a new one based on that, which scales the values going into it, so if we called this provider with (47,24), those values would get scaled down to (2.35, 1.2) and those values would be passed into the noise function. Since they are not on integer boundaries, the noise function will return a non-zero value. Hurrah! However, this is still a really small value, and while you will see some hills, they will be very small. So, we want to multiply the returned height to create bigger peaks which we can do with the mul method. That returns a provider that takes the value from the previous one and multiplies the value by 10. What do you get now?

I’ll wait here while you fly around for half an hour…..

You can play around with the scale and mul parameters, keeping them in the same proportion generates a similar landscape, it will just be scaled up or down proportionally. If you decrease just the scale it stretches the map out and the hills look shorter. Increase the mul parameter and the hills will grow taller and shorter.

Also, as you ramp the values up and down, you find you go through your landscape faster or slower. You can change the flyCam speed to fix that.

Note that you only have 513 X 513 quads in this scene, so you can’t stretch the map out forever as the number of quads in the geometry will decrease and your hills will just end up a sharp triangle. You can always increase the MAP_SIZE, just remember to keep it as multiples of (2^n)+1.

In part 3, we will look at producing a better landscape using more complex height provider implementation and layered noise.

This year I’m getting a head start, and to celebrate that, I’m going to blog it as I go. I’m going to be using Java with JMonkeyEngine APIs on top of the LWJGL OpenGL libs. I quite like JMonkeyEngine as it puts more control into your code giving with the power of the Java language. Being Java based means it is flexible enough to use some good design patterns and code structure without too much rigidity and I can unit test my logic too!

So, with that, I’m going to create a Maven project which will pull in the JMonkeyEngine libs and create a very simple, cube lit by a sun. I’m going to be using Java 13 and the latest JMonkeyEngine version (3.2.4 -stable). If you’ve looked at JME before, this probably isn’t going to be anything earth shattering, but serves as a solid ground for part II.

Start by creating a new simple Maven project and add the following content in the pom.xml file.

	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<maven.compiler.source>13</maven.compiler.source>
		<maven.compiler.target>13</maven.compiler.target>
		<jme-version>3.2.4-stable</jme-version>
	</properties>

	<repositories>
		<repository>
			<id>JCenter</id>
			<url>https://jcenter.bintray.com/</url>
		</repository>
	</repositories>

	<dependencies>
		<dependency>
			<groupId>org.jmonkeyengine</groupId>
			<artifactId>jme3-core</artifactId>
			<version>${jme-version}</version>
		</dependency>

		<dependency>
			<groupId>org.jmonkeyengine</groupId>
			<artifactId>jme3-terrain</artifactId>
			<version>${jme-version}</version>
		</dependency>

		<dependency>
			<groupId>org.jmonkeyengine</groupId>
			<artifactId>jme3-plugins</artifactId>
			<version>${jme-version}</version>
		</dependency>

		<dependency>
			<groupId>org.jmonkeyengine</groupId>
			<artifactId>jme3-lwjgl</artifactId>
			<version>${jme-version}</version>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>3.8.0</version>
				<configuration>
					<source>${maven.compiler.source}</source>
					<target>${maven.compiler.target}</target>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Now at some point, you will have to download the JMonkeyEngine SDK to get the binary libraries to use with JME. For now, we just need one, which is liblwjgl64.so. Your filename may be different depending on the platform and 32/64 bit. This is the lib for supporting the LWJGL and for now, can go in the root of the project folder, next to the pom.xml file.

Our next step it to write a piece of code which will get us displaying some graphics in a page. We’ll create a main class which inherited from the SimpleApplication class in the JME library.

import com.jme3.app.SimpleApplication;

public class Main extends SimpleApplication {

  public static void main(final String[] args) {
    final Main app = new Main();
    app.start();
  }

  @Override
  public void simpleInitApp() {

  }
}

Run that and you should get the JMonkeyEngine splash screen where you can pick your settings, and upon clicking OK, you should see a big black screen with some debug information on it:

Not much is going on here, just some debug information including our FPS rate. Of course, we haven’t added anything to the display yet. So we need to add some light and an object. We’ll also position the camera from where we are generating the image so we can get a good view. We’ll do this in the simpleInitApp method that is used to initialise the content.

  @Override
  public void simpleInitApp() {

    // move up, to the side and look at the origin
    getCamera().setLocation(new Vector3f(-4, 5, 10));
    getCamera().lookAt(Vector3f.ZERO, Vector3f.UNIT_Y);

    // lets put some light in
    final DirectionalLight sun = new DirectionalLight(new Vector3f(0.2f, -0.6f, -0.5f).normalize());
    sun.setColor(ColorRGBA.White);
    rootNode.addLight(sun);

    // create a simple box
    final Box b = new Box(1, 1, 1);
    final Geometry geom = new Geometry("Box", b);

    // create a very plain lit material
    final Material mat = new Material(assetManager, "Common/MatDefs/Light/Lighting.j3md");

    // assign this material to the box geometry.
    geom.setMaterial(mat);

    // add the geometry to the scene and we are good to go
    rootNode.attachChild(geom);
  }

This article isn’t meant to be primer on 3D graphics, or JMonkeyEngine in particular, but this is a simple application that will get you up and running with a simple lit scene in JME with Java.

We move the camera and look at the box so we can see all 3 sides and get an idea of how they are shaded. The directional light has no position so its only influence on shading depends solely on the angle between the box face and the direction of the light that was specified in the constructor. The material we have used is a simple lit material using the default parameters.

If you run this, you will see a simple scene with a lit box that you can use the mouse to look around with and the WASD keys to move around in.

This gets us up and running with JME. Next time we’ll look at creating a simple terrain using code, in particular the JME noise functions to create terrain.

As per their issue archives page, it seems they have converted the last few issues to HTML while other issues are still available as a PDF download.

Historically, magazines have provided an opportunity to expose the reader to new topics which they might not have otherwise found by covering a wide range of articles focused around a central topic. In the past, I’ve found Java Magazine has provided a casual introduction to a number of new ideas and concepts and a worthy revisitation of old ones.

With its new monthly publishing schedule it’s certainly one to add to the bookmarks.

When returning a value from a method, you want to return one of three things, either return the actual result, return an unknown (null) value, or throw an exception.
The first case is the happy path which most developers code for as it hopefully meets most cases. Returning a null can often be overlooked unless the developer is very conscientious or there is already an expectation that the result is likely to be null. The third option is that an exception can be thrown from the method if it is unable to complete the operation. The problem here is that we have a fairly loose contract with the client and leave it up to the caller to be aware of the different outcomes.

Once we have a value from a method, you typically want to do one of three things when it is null. Use a default value, throw an exception or change program flow to not use it. The following 3 examples show how this is done in a pre-Optional world:

//Throw Exception
Integer size = calculateSize();
if (size == null) {
  throw new NullPointerException("Couldn't calculate size");
}
//do something with size.


 
//Default Value
Integer size = calculateSize();
if (size == null) {
  size = DEFAULT_SIZE;
}
allocateSpace(size);


//Different code path:
Integer size = calculateSize();
if (size != null) {
  allocateSpace(size);
}

//carry on

Because we have always been able to deal with null values like this, I wasn’t blown away by the prospect of the Optional class. However, the problem with the above is that we must always remember to handle a null result and inevitably at some point, someone will end up writing :

Integer size = calculateSize();
allocateSpace(size);

This will create code that is prone to sporadic unhandled failures. In general we want our code to be robust, easy to use and offer the least surprises.

To avoid repeating this in every invocation, we could roll the logic into our function so calculateSize() will throw an exception or return a default value. However, we might not always know which we want to do since it would depend on the context it was called in.

Optionals To The Rescue

Optional values allow us to always return an object that acts as a container for the actual value that may or may not be null. We typically create a new Optional using either :

return Optional.of(result);

or

return Optional.ofNullable(possibleNullValue);

If the value you return may be null, you should use the latter version otherwise an exception will be thrown if you invoke the first syntax with a null value.

Optional values enable us to define the signature of the method to say the outcome could well be null and force the client to deal with it.

We can query the returned Optional value and handle it differently depending on whether there is a value or not. Here are the same above 3 cases implemented as an Optional value returned from calculateSize():

//Default Value
Integer size = calculateSize().orElse(DEFAULT_SIZE);
allocateSpace(size);

//Throw Exception
Integer size = calculateSize().orElseThrow(()->new RuntimeException("Couldn't calculate size"));
allocateSpace(size);

//Different code path
calculateSize().ifPresent(s-> allocateSpace(s));

The real value of the Optional class is the semantics to say that this value could be null, forcing the developer to deal with it and providing convenience for handling null values in a different way. Granted, just as before, someone could just incorrectly write :

Integer size = calculateSize().get();
allocateSpace(size);

But there are static analysis tools that can detect such code smells where you access an optional without checking it, and if you have proper unit test coverage (such that calculateSize returns an empty Optional) this code should be invoked with an empty optional and an error thrown.

Improving clarity.

When we return the actual object, callers of the method don’t know whether null could be returned or if the method will throw an exception without looking at either the method signature or java doc. When returning an Optional, you can safely assume that the value can be null and code defensively for it either by using one of the above solutions.

Rules to code by:

• If a value will always be returned then return the actual type.
• If the method could return null, then return an Optional to let the caller know this is the case and force the client to deal with the result.
• Throw an exception, select default or change the program flow based on the result for the appropriate context of the caller.