Joomla! Open Source Content Management

Installing SOLoist

Before you start working with SOLoist, you have to prepare your system for Java EE development. You will need the following: Java JDK, Eclipse IDE, Apache Tomcat, and StarUML.

If you already have all these installed on your machine, you may skip the System Requirements section.

After installing the required software, it is recommended that you download the Empty Project which is already prepared for SOLoist development.

System Requirements

Java

Since SOLoist is a Java-based framework, you have to install Java first. SOLoist works with Java 1.6 JDK or later. It can be downloaded from Oracle Website.

Application Server

For executing SOLoist applications, you need to have an application server. This example assumes you have installed Apache Tomcat. SOLoist works with versions 5.5, 6, and 7, which can be downloaded from Apache Tomcat Website.

Eclipse

In this tutorial (and other tutorials on this site) we use Eclipse IDE, but any other Java IDE can be used. Eclipse IDE for Java EE development can be downloaded from Eclipse Website.

Database

SOLoist framework currently officially supports the following databases: MySQL, Oracle, and Sybase SQL Anywhere. Before starting working with SOLoist, you should install one of the supported databases, create a new schema and/or a user in the database, and give the appropriate privileges to the user.

In the SOLoist Tutorial, we used MySQL database, which can be downloaded from MySQL Website.

StarUML

Being an executable UML framework, SOLoist requires a UML modeling tool. At this moment, we only support StarUML (V1), but other modeling tools will be supported in the future. StarUML is an open source UML/MDA patform and can be freely downloaded form Star UML (V1) on Sourceforge.

After installing StarUML, you have to download and install SOLoist plugin for StarUML.

Then download the Frameworks archive and extract Frameworks folder directly into ...\StarUML\modules\staruml-javasol\ (e.g. C:\Program Files (x86)\StarUML\modules\staruml-javasol\Frameworks).

Running Empty Project in Eclipse

After downloading the Empty Project archive file, you should unzip it somewhere in your file system. Inside the EmptySOLoistProject folder, you will find the model folder which contains an empty StarUML model (emptymodel.uml) that you can use to create your own domain models.

The EmptySOLoistProject folder contains an Eclipse project that can be imported into a workspace. To import this project into Eclipse, you should select Import from the File menu and choose Maven -> Existing Maven Project into Workspace.

After importing the project, right click the project and select Maven -> Update Project... and then OK. Before doing this, make sure that SOLoist libraries are already stored in your maven repository so they can be fetched during the project build process.

Navigate to the folder which contains EmptySOLoistProject. Check it in the list and click Finish.

If the Tomcat is not already installed, you will probably see a few errors in the project. That's still fine, because you need to configure the application server.

Select the Servers tab, click on new server wizard... or right click on the empty space and select New -> Server. Find Apache Server v7.0 (or an earlier version if you wish) in the list of the available application servers, select it, and click Next.

Provide the directory where you installed Tomcat and click Next.

Configure the EmptySOLoistProject on the server by selecting it and adding it to the Configured list. Click Finish.

You also need to configure the targeted runtimes for your project. You can do so by going to Project's Properties (right click on the project -> Properties), Targeted Runtimes. Check Apache Tomcat v7.0 (or another version that you have installed).

At this point, you should have no errors in your project. The structure of the project should be as in the figure below.

Note that there are two folders for the source code in this project: src and init. SOLoist configuration files are stored in the src folder. SOLoist follows the convention over configuration principle, so there is a minimum of configuration required:

1. Enter the database name, username and password into db.properties file. For more details see the SOLoist Database Configuration wiki page.
2. Setup the file repository path in soloist-config.xml.
3. Set the log file path in log4j.xml.

More details about configuration can be found on the SOLoist Configuration wiki page.

You are now ready to start you first SOLoist application. Start the server by right clicking it and selecting Start.

Now visit: http://localhost:8080/emptyproject/index.html in your browser to see your first SOLoist app at work!

Extending The Empty Project

Now that you have a basic application running, it's now the time to build something yourself! This section will teach you how to properly set up and create a simple domain model, generate the Java code, the database schema, and initialize the database with data. We will only touch on GUI development, but you should go through our more complete tutorial.

Preparing the domain model

First, let's create a domain package. In StarUML, right click on the model in Model Explorer (StarUML's default <<designModel>> Design Model), select Add -> Package, and name it with the stereotype <<domain>> (e.g. <<domain>>hospital).

Create a new class diagram by right clicking on the domain package, then go to Add Diagram -> Class Diagram and give it a descriptive name (e.g. hospital).

Before we can create domain classes, we need to import the SOLoist built-in library. It is useful as documentation, but more importantly our domain model relies on its built-in datatypes, commands, etc. To import the framework in StarUML, go to File -> Import -> Framework... and choose the framework you want to import (SOLoist Framework). If you cannot find the SOLoist Framework in the list, you have probably skipped this step.

Then select the package where you want to import the framework.

Creating domain classes

Now, let's create a simple class Doctor. We are still in StarUML. Choose the class tool from the toolbox and click on the diagram. Name the class and press Enter. Add an attribute name of SOLoist type Text (right click on the class and select Add -> Attribute). It is important that StarUML recognizes that Text is the type from the previously imported framework. To verify this, select the attribute in Model Explorer, then select Type field in the Properties tab below. Clicking on the ellipsis button will open a dialog which should show the selected type Text from SOLoist.

Similarly to adding an attribute, add the operation heal().

Code generation

Now, we should generate SOLoist Java code from StarUML. We need to set the path where generated files will end up. To do that you first have to include the JavaSOL profile into the model. This will add additional options to UML elements, like the code generation path. Press Ctrl + F8 or go to Model -> Profiles..., choose the JavaSOL profile and click on Include.

Right click on your model (Design Model) in Model Explorer and click on Tagged Values. You will see an additional JavaSOL tab with one tagged value named CodeGenerationPath. The default value is c:\temp, but you should change it to the source folder of your project (e.g. D:\used\EmptySOLoistProject\src).

You can generate the code for one single class, or for an entire package, or for the entire model (note that this will generate code even for the imported SOLoist package). Right click on the domain package (hospital), go to SOL Java Plug-In -> Generate SOLoist Code. Switch to Eclipse, refresh it, and you will find the Doctor class inside the hospital package.

Let's take a look at the generated class. The only part that you should change manually is the heal() method body. Notice the comments in the form // ---------<SOL id="6d3bc142-e042-4df2-96d9-b9eaa0981e9e:___body___" /> - these enclose the so-called preserved sections.

Everything written between these comments will be preserved if you run the code generator again and regenerate the code for the same part of the model. That means that method implementations should be inside the method body's preserved section. Every class has three preserved sections: cbeg (beggining of the class), cend (end of the class) and fend (end of file). Additionally, every method has two preserved sections: throw (for throws clause) and body (for the method body).

//Generated: by JavaSol plugin
package hospital;

import rs.sol.soloist.modelreader.Repository;
import rs.sol.soloist.server.builtindomains.builtindatatypes.Text;
import rs.sol.soloist.server.builtindomains.common.ObjectOfClass;
import rs.sol.soloist.server.javaimpl.runtime.SOLoistAttributeValue;
import rs.sol.soloist.server.javaimpl.runtime.SOLoistCreateInstanceRequest;
import rs.sol.soloist.server.uml.concepts.reflection.IClass;
import rs.sol.soloist.server.uml.concepts.reflection.IProperty;
import rs.sol.soloist.server.uml.concepts.runtime.IAttributeValue;
import rs.sol.soloist.server.uml.concepts.runtime.IObjectID;

public class Doctor extends ObjectOfClass {
    // -------------<SOL id="abc63313-1017-4949-9314-74a4fa5f1e4b:___cbeg___" />
    // -------------<LOS id="abc63313-1017-4949-9314-74a4fa5f1e4b:___cbeg___" />
    public final IAttributeValue<Text> name = new SOLoistAttributeValue<Text>(PROPERTIES.name, this);
    /**
     * Fully qualified UML class name
     */
    public static final String FQ_TYPE_NAME = "hospital::Doctor";
    /**
     * UML class reference
     */
    public static final IClass CLASSIFIER = Repository.getRepository().getUMLClass(FQ_TYPE_NAME);

    public static final class FQPropertyNames {
        public static final String name = "hospital::Doctor::name";
        private FQPropertyNames() { }
    }

    public static final class PROPERTIES {
        public static final IProperty name = Repository.getRepository().getProperty(FQPropertyNames.name);
        private PROPERTIES() { }
    }
    
    protected Doctor(IObjectID objID)
    {
        super(objID);
    }
    
    protected Doctor(SOLoistCreateInstanceRequest req)
    {
        super(req);
    }
    
    public Doctor()
    {
        this(new SOLoistCreateInstanceRequest(CLASSIFIER));
        constructor();
        completeRequest();
    }
    
    public void heal() 
    // -------------<SOL id="6d3bc142-e042-4df2-96d9-b9eaa0981e9e:___throw__" />
    // -------------<LOS id="6d3bc142-e042-4df2-96d9-b9eaa0981e9e:___throw__" />
    {
        // ---------<SOL id="6d3bc142-e042-4df2-96d9-b9eaa0981e9e:___body___" />
        // TODO: implement this
        throw new RuntimeException("Not Implemented");
        // ---------<LOS id="6d3bc142-e042-4df2-96d9-b9eaa0981e9e:___body___" />
    }

    // -------------<SOL id="abc63313-1017-4949-9314-74a4fa5f1e4b:___cend___" />
    // -------------<LOS id="abc63313-1017-4949-9314-74a4fa5f1e4b:___cend___" />
}

// -----------------<SOL id="abc63313-1017-4949-9314-74a4fa5f1e4b:___fend___" />
// -----------------<LOS id="abc63313-1017-4949-9314-74a4fa5f1e4b:___fend___" />

Generating the database schema

SOLoist's integrated ORM automatically generates the database schema based on the domain model. It needs an XMI file as an input. To export the XMI from StarUML, go to File -> Export -> XMI... Browse to the project's src folder, and overwrite emptyproject.xmi.

Open web.xml in Eclipse and make sure that the listener demo.contextlisteners.ObjectSpaceInitContextListener is declared. Now start the server. You will see console messages: Dropping obsolete tables, Creating tables and indexes. SOLoist saves the DDL into a special table, and when the server starts, it compares the current DDL with the previous one. If they are the same, the data is truncated, but if there is a difference, all existing tables will be dropped and new ones will be created.

Loading data into the database

After generating the schema, SOLoist can initialize the object space. Creating new objects and persisting them is easy: just open the ObjectSpaceInit class in Eclipse and implement its init() method. All you need to do is to create objects through SOLoist API, and they will be automagically persisted into the database. Try this:

	@Override
	public void init() throws InitializerFailedException {
		Doctor d1 = new Doctor();
		d1.name.set(Text.fromString("Henry Gray"));
		Doctor d2 = new Doctor();
		d2.name.set(Text.fromString("Joseph Lister"));
	}

Start the server again. Now, take a look at the database (look for the doctor table) or use SOLoistExplorer (http://localhost:8080/EmptySOLoistProject/oql).

Next Steps

At the moment, EmptySOLoistProject has a very simple GUI - a "Hello World" label inside the vertical panel. Look for the EmptyApplication class in Eclipse. You could explore GUI API yourself, but we advise you to go through this tutorial.