Sigil - Eclipse Plugin Quick Start

Eclipse Plugin Quick Start

Short Cuts

Cheat Sheet (contributed by Paremus, Ltd.)
Guided Tutorial (contributed by Zigor Salvador)
Modifications for Remote Binding (contributed by Zigor Salvador)

Please submit comments/corrections to the Newton User newsletter.

Cheat Sheet

The best way to get started with Sigil is to follow the "Hello World" cheat sheet which runs through the basic operations of building and running a simple application with Sigil.

To access this cheat sheet use "Help -> Cheat Sheets... -> Sigil -> Create a Hello World composite application".

Guided Tutorial

Although the cheat sheet is a good approach to Sigil, this guided tutorial will show you how to build a multiproject "Hello World" application with screenshots, code and some insights from a Newton beginner.

The tutorial consists of 7 steps:

Step 1 - Verify your Newton install
Step 2 - Create the Sigil projects
Step 3 - Complete the NewtonInterface project
Step 4 - Complete the NewtonService project
Step 5 - Complete the NewtonClient project
Step 6 - Launch a Newton container
Step 7 - Install and run the composites

1 - Verify your Newton install

This step is aimed at making sure your system meets the software requirements for the tutorial.

1.1 - Download the latest Newton release from Code Cauldron.

1.2 - Extract the contents of the Newton release to a folder in your local hard drive.

1.3 - Install the Sigil plugin following these instructions.

1.4 - Check that the Sigil plugin is linked to your local Newton install in Eclipse's preferences.

1.5 - When your Sigil plugin is linked to your Newton install, you can proceed to Step 2 - Create the Sigil projects.

2 - Create the Sigil projects

This step involves creating the required project structure for the tutorial.

2.1 - Create a new Sigil project to host our "HelloWorld" interface.

2.2 - In the project wizard window, choose "Sigil Project" and click "next".

2.3 - In the Sigil project window, enter "NewtonInterface" and click "finish".

2.4 - Once the new Sigil project is created, your Eclipse workspace should look like this.

NOTE - The "sigil.properties" file is a key component of Sigil...

2.5 - Repeat the steps and create a new Sigil project to host the "HelloWorld" service (name it "NewtonService").

2.6 - Repeat the steps and create a new Sigil project to host the "HelloWorld" client (name it "NewtonClient").

2.7 - Once all Sigil projects are created, your Eclipse workspace should look like this.

3 - Complete the "NewtonInterface" project

This step completes the Java aspect of the "NewtonInterface" project.

3.1 - Create a new "HelloWorld" interface in the "NewtonInterface" project.

3.2 - The code for the newly created interface is:

package org.example.api;

public interface HelloWorld
{
	public String getHelloWorld ();
}

4 - Complete the "NewtonService" project

This step completes the Java and SCA aspects of the "NewtonService" project.

4.1 - Create a new "HelloWorldService" class in the "NewtonService" project.

The code for the newly created class is:

package org.example.server;

public class HelloWorldService implements HelloWorld
{

}

4.2 - Eclipse will complain about the "HelloWorld" interface not being present in the project's classpath.

4.3 - Hover the mouse over "HelloWorld" and accept the suggested fix to "Import org.example.api.HelloWorld from NewtonInterface".

4.4 Sigil will prompt you to export the "HelloWorld" interface from the "NewtonInterface" project.

NOTE - Both the import and the export will be reflected in their respective "sigil.properties" files...

4.5 - The import statement will be added to your code, and a new error will be displayed.

4.6 - Hover the mouse over "HelloWorld" and accept the suggested fix to "Add unimplemented methods".

4.7 - Complete the method in order to implement the "HelloWorld" interface.

The code for the final "HelloWorldService" class is:

package org.example.server;

import org.example.api.HelloWorld;

public class HelloWorldService implements HelloWorld
{
	public String getHelloWorld()
	{
		return "Hello World!";
	}
}

4.8 - So far, we have dealt with the Java aspect of the "HelloWorld" service.

4.9 - To deal with the SCA aspect of the service, we need to create a "sca" folder in the "NewtonService" project.

4.10 - Create a new composite in the "NewtonService" project, selecting "New -> Other... -> Sigil -> SCA Composite".

4.10 - Enter "NewtonService" as the composite name and store the composite file in the "sca" folder of the project.

Following is the XML code for the NewtonService.composite file:

<?xml version='1.0' encoding='utf-8'?>

<composite name="NewtonService">
  
  <description>Description...</description>
  
  <bundle.root bundle="NewtonService" version="1.0.0"/>

  <service name="interface">
	<interface.java interface="org.example.api.HelloWorld"/>
  	<binding.osgi/>
  </service>
  
  <component name="implementation">
	<implementation.java.callback impl="org.example.server.HelloWorldService"/>
  </component>
  
  <wire>
	<source.uri>interface</source.uri>
    <target.uri>implementation</target.uri>
  </wire>

</composite>

4.11 - Save the composite, and open the "sigil.properties" file to view its "Exports" tab.

4.12 - In the "Composites" section, click "Add".

4.13 - Select the "NewtonService" composite from the list and click "OK".

4.14 - Save the changes to the "sigil.properties" file.

NOTE - Saving the changes triggers Sigil to build the project and produce the "NewtonService" bundle under /build/lib...

5 - Complete the NewtonClient project

This final coding step completes the Java and SCA aspects of the "NewtonClient" project.

5.1 - Create a new "HelloWorldClient" class in the "NewtonClient" project.

The code for the newly created class is:

package org.example.client;

public class HelloWorldClient
{
	HelloWorld helloWorld = null;

	public void addServiceReference (HelloWorld helloWorld)
	{
		this.helloWorld = helloWorld;

                System.out.println("***" + this.helloWorld.getHelloWorld() + "***");
	}
	
	public void removeServiceReference (HelloWorld helloWorld)
	{
		this.helloWorld = null;
	}
}

NOTE - The "add" and "remove" methods of this class are related to the "reference name" tag of the SCA composite we'll now create...

5.2 - Create a "sca" folder in the "NewtonClient" project to store the SCA Composite file.

5.3 - Create a new composite in the "NewtonClient" project, selecting "New -> Other... -> Sigil -> SCA Composite".

5.4 - Enter "NewtonClient" as the composite name and store the composite file in the "sca" folder of the project.

Following is the XML code for the NewtonClient.composite file:

<?xml version='1.0' encoding='utf-8'?>

<composite name="NewtonClient">

  <description>Description...</description>
  
  <bundle.root bundle="NewtonClient" version="1.0.0"/>
    
  <reference name="interface" multiplicity="0..1">
  	<interface.java interface="org.example.api.HelloWorld"/>
  	<binding.osgi/>
  </reference>
  
  <component name="client">
    <reference name="ServiceReference"/>
    <implementation.java.callback impl="org.example.client.HelloWorldClient"/>
  </component>
  
  <wire>
    <source.uri>client/ServiceReference</source.uri>
    <target.uri>interface</target.uri>
  </wire>
  
</composite>

NOTE - Notice the "reference name" tag and its relation with the two Java methods in the class...

5.5 - Add the newly created composite to the "sigil.properties" file of the "NewtonClient" project.

5.6 - Remember to save the changes to the "sigil.properties" file in order to trigger the tooling process.

6 - Launch a Newton container

Right now, the required Newton bundles are ready to roll and this step launches the Newton container that will host them.

6.1 - Open any of the "sigil.properties" files and click the "Launch a newton container" link of its "Overview" tab.

6.2 - Some background loading will take place as the container is assembled.

6.3 - The console will let you know when the startup process is done with a "Boot complete" message.

7 - Install and run the composites

The moment of truth.

7.1 - Right click one of the SCA Composite files and choose "Install Composite" from the contextual menu.

7.2 - Repeat this procedure with the other composite and the console will output "*** Hello World! ***".

NOTE - Newton manages the binding process and links the client to the service as soon as both entities are present...

Modifications for Remote Binding

How to turn the Hello World example into a distributed Hello World.

1 - Modify both SCA Composite files and change <binding.osgi> for <binding.rmi>

2 - Start the Newton container in the "Overview" tab of a Sigil pane.

3 - Start the distributed Newton infrastructure with the following commands (using the Eclipse Console to enter text):

exec etc/scripts/single-jvm-dist-infra
cds publish remote etc/cds/jini-service-bundles.xml

4 - Install both composites in the same container, or launch two separate containers and install one composite in each.