Version
1.1.0
Date
24 July 2016
Authors
Vorachet Jaroensawas, Koneksys (vorachet.jaroensawas@koneksys.com)
Axel Reichwein, Koneksys (axel.reichwein@koneksys.com)
Hubertus Tummeshceit (hubertus.tummescheit@modelon.com)
1. Summary
2. Understanding OSLC FMI Adapter Components
3. Building OSLC FMI Adapter
3.1 Building and Testing C component (optional)
3.1.1 To build FMIClient from a terminal command line in Linux or Mac
To build FMI Library source
To run FMIClient build script for Mac
To run FMIClient build script for Linux
To install the executable files of FMIClient into OSLC FMI adapter java project
3.1.2 To build FMIClient from the Developer Command Prompt for VS2013 in Windows To run FMIClient build script for Windows
To install the executable files of FMIClient into OSLC FMI adapter java project
3.1.3 Run a quick test for the FMIClient from a terminal command line
3.2 Building and Testing Java components
3.2.1 Installing OSLC4J
3.2.2 Importing projects into the Eclipse workspace
3.2.3 Building the oslc4j-fmi projects
3.2.4 Running the OSLC FMI Adapter with sample FMUs
Option1: Running the OSLC FMI Adapter using Embedded Tomcat
Option2: Deploying the OSLC FMI Adapter on a Tomcat server Configuring repository of FMU files
The settings of conf.properties
3.2.5 Testing the OSLC FMI Adapter Manually
Testing the retrieval of OSLC resources in HTML
Testing the retrieval of OSLC resources in RDF
3.2.6 Testing the OSLC FMI Adapter using JUnit
Running JUnit Test Suite of OSLC FMI Adapter
4. URI Specifications
5. OSLC FMI Adapter Entity Classes
6. Third party libraries
OSLC4j-FMI is intended as a OSLC adapter for publishing FMUs (Functional Mockup Units) that follow FMI Standard. This version of the library supports FMI 1.0 and FMI 2.0. See http://www.fmi-standard.org. The interface was developed for Modelon by Koneksys. The C-language part is based on the open source FMI-Library by Modelon, and the Java-language part on oslc4j by Koneksys.
OSLC4J-FMI consists of two parts.
The OSLC FMI adapter C component uses VISUAL STUDIO COMMUNITY 2013 (see https:// www.visualstudio.com/downloads/download-visual-studio-vs) to compile a C program used to interface FMUs for Windows and use GCC for Linux or Mac. List of C project
oslc4j-fmi-cinterface
Contains FMIClient source and build scripts, FMI Library source and Windows binaries.
The OSLC FMI adapter java components use Maven (see http://maven.apache.org) for a build automation tool. List of Java projects
oslc4j-fmi-build
Top-level maven build script
oslc4j-fmi-ecore
ECore definition for the OSLC FMI adapter entity classes
oslc4j-fmi-resources
Java entity classes for the OSLC FMI adapter which are generated by oslc4j-fmi-ecore
oslc4j-fmi-clients
JUnit tests and example test clients for the OSLC FMI adapter
oslc4j-fmi
Java web component for the OSLC FMI adapter
This step is optional because all executable files of the FMIClient on each platform are installed in the following folder. The following directory structure and FMIClient must be available in the com.modelon.oslc.adapter.fmi java project before running the OSLC FMI adapter. By default, the latest version of the FMIClient on each platform is provided.
com.modelon.oslc.adapter.fmi
/conf
/fmi
/bin
/darwin64
FMIClient
fmilib_shared.dylib
/linux64
FMIClient
libfmilib_shared.so
/win32
FMIClient.exe
msvcr120d.dll
fmilib_shared.dll
/win64
FMIClient.exe
msvcr120d.dll
fmilib_shared.dll
If you want to build FMIClient from source, use instructions in the next section.
CMake (see http://www.cmake.org) is used to generate the native build scripts for the FMI Library. CMake 3.3.0 is tested in development of this project on Linux and Mac. For Windows, we use FMI Library binary directly from http://www.fmi-standard.org. The recommended version of the FMI Library binaries for Windows and source is2.0.2b3 which are already prepared in com.modelon.oslc.adapter.fmi.cinterface/fmi directory of project. To build FMI Library source
Download FMIL 2.0.2b3 source file from http://www.jmodelica.org/downloads/FMIL/FMILibrary-2.0.2b3-src.zip
and extract to com.modelon.oslc.adapter.fmi.cinterface/fmi/FMILibrary-2.0.2b3-src
git clone https://github.com/ld4mbse/oslc-adapter-fmi
cd com.modelon.oslc.adapter.fmi.cinterface
cd fmi
cd FMILibrary-2.0.2b3-src
mkdir build
cd build
cmake -DFMILIB_INSTALL_PREFIX=../install ../
make install test
When you successfully build the FMI library, the following folder will be created.
com.modelon.oslc.adapter.fmi.cinterface
/fmi
/FMILibrary-2.0.2b3-src
/install
/doc/
/include/
/lib/
To run FMIClient build script for Mac
cd com.modelon.oslc.adapter.fmi.cinterface/src/FMIClient
./build.mac.sh
The output of the build script build.mac.sh will be
com.modelon.oslc.adapter.fmi.cinterface
/src
/FMIClient
/install
FMIClient
fmilib_shared.dylib
To run FMIClient build script for Linux
cd com.modelon.oslc.adapter.fmi.cinterface/src/FMIClient
./build.linux.sh
The output of the build script build.linux.sh will be
com.modelon.oslc.adapter.fmi.cinterface
/src
/FMIClient
/install
FMIClient
libfmilib_shared.so
To install the executable files of FMIClient into OSLC FMI adapter java project
For Mac
com.modelon.oslc.adapter.fmi /conf
/fmi
/bin
/darwin64
FMIClient
fmilib_shared.dylib
For Linux 64 bit
com.modelon.oslc.adapter.fmi /conf
/fmi
/bin
/linux64
FMIClient
libfmilib_shared.so
VISUAL STUDIO COMMUNITY 2013 is available to download at https://www.visualstudio.com/ downloads/download-visual-studio-vs . To prevent common errors in calling cl.exe of the Visual Studio, to use default installation path at "C:\Program Files\Microsoft Visual Studio 12.0" is recommended and make sure Visual C++ and its build tool is available in "C:\Program Files\Microsoft Visual Studio 12.0\VC". The Developer Command Prompt for VS2013 is available in Program Menu > Visual Studio 20130 > Visual Studio Tools To run FMIClient build script for Windows
cd com.modelon.oslc.adapter.fmi.cinterface\src\FMIClient build.bat
The output of the build script build.bat will be
com.modelon.oslc.adapter.fmi.cinterface
/src
/FMIClient
FMIClient.exe
FMIClient.obj
msvcr120d.dll
fmilib_shared.dll
To install the executable files of FMIClient into OSLC FMI adapter java project For Windows 32bit
com.modelon.oslc.adapter.fmi
/conf
/fmi
/bin
/win32
FMIClient.exe
msvcr120d.dll
fmilib_shared.dll
For Windows 64bit
com.modelon.oslc.adapter.fmi
/conf
/fmi
/bin
/win64
FMIClient.exe
msvcr120d.dll
fmilib_shared.dll
FMIClient test command line:
FMIClient read <FMUFilePath> <TempFolder>
Example of FMIClient test command line:
FMIClient read FMI1.0_CS_CoupledClutches.fmu c:\temp\
FMIClient read FMI2.0_CS_PID_Controller.fmu c:\temp\
Notes:
- is relative or absolute path of a FMU
- must be created before running the command line
Eclipse IDE for Java EE Developers is recommended for building the OSLC FMI adapter Java components and running development mode of the adapter. The Eclipse IDE is available to download at http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/mars2
- Follow the instructions to install OSLC4J at https://github.com/ld4mbse/oslc4j
- In Eclipse, import projects from Git. (File -> Import -> Git -> Projects from Git)
- Click on the Clone Repository icon
- In the URI field, paste the following URL: https://github.com/ld4mbse/oslc-adapter-fmi
- The Host and Repository fields will autofill.
- Click Next, only select the master branch
- Click Next until Finish.
- Select a wizard to use for importing projects, only select Import existing Eclipse projects
- There are 5 projects including oslc4j-fmi, oslc4j-fmi-build, oslc4j-fmi-cinterface, oslc4j-fmi-ecore, oslc4j-fmi-resources are in the list to be imported.
- Select all 5 projects and click Finish
- The 5 projects are in the Eclipse Project Explorer
- In Eclipse, open the Project Explorer view. (Window -> Show
- View -> Project Explorer)
- Expand the oslc4j-fmi-build project
- Right click pom.xml -> Run As -> Maven clean
- Right click pom.xml -> Run As -> Maven install
The OSLC FMI Adapter provides sample FMU files for each platform which are prepared in the Eclipse project.
The Development Mode allows you developing and testing the web application easily through development lifecycle using Eclipse and Maven.
You can also consider this mode as an easiest way to run the OSLC FMI Adapter with the sample FMU files is to run the adapter with the Apache Tomcat Maven Plugin and Embedded Tomcat which are pre-configured in the oslc4j-fmi project.
- In Eclipse, open the Project Explorer view. (Window -> Show View -> Project Explorer)
- Expand the oslc4j-fmi project
- Right click pom.xml -> Run As -> Run Configurations
- In Run Configurations Dialog, Right click Maven Build -> New
- In the right hand side, Name text input, enter "Run OSLC FMI Adapter".
- In the right hand side, Base directory text input, click Browse Workspace and click workspace oslc4j-fmi. After the workspace is clicked, text {workspace_loc:/oslc4j-fmi} should be appeared in the Base directory text input
- In the right hand side, Goals text input, enter �tomcat7:run
- Click run (Once you create this Maven goal in Eclipse you can simply run it again in Eclipse Run menu icon or Menu Run -> Run History)
- After Tomcat is successfully started, open URL http://localhost:8686/oslc4jfmi/services/catalog
This section describes steps to deploy the OSLC FMI Adapter with sample FMU files on a Tomcat server.
The differentiation between Development Mode Tomcat Port and Production Mode Tomcat Port: With Development Mode Tomcat, the OSLC FMI adapter service will run on your local machine using port 8686. for development purpose. When you want to deploy the adapter on Production Mode Tomcat, the port of OSLC FMI adapter service will be managed by the Tomcat server configuration. For example, if you running Tomcat on port 8080, so the OSLC FMI adapter service will run on port 8080.
- In Eclipse, open the Project Explorer view. (Window -> Show View -> Project Explorer)
- Expand the oslc4j-fmi project
- Copy the folder named fmi under the conf folder (See section 5 for more detail of the configuration directory)
- Paste the folder in the Tomcat installation directory (Example: C:\Program Files\apache-tomcat-8.0.24-windows-x64\apache-tomcat-8.0.24\fmi)
- In Eclipse, expand the oslc4-jfmi project
- Open the /target folder
- Rename the oslc4j-fmi-1.1.0.war file into oslc4jfmi.war
- Copy oslc4jfmi.war into the /webapps folder of the of the Tomcat installation directory
- tart Tomcat
- Open URL http://:/oslc4jfmi/services/catalog
- If you running Tomcat on localhost using port 8080, so the URL is http://localhost:8080/oslc4jfmi/services/catalog
The OSLC FMI Adapter allows you to configure the location of FMU files.
By default, the following configuration directory is prepared in the Eclipse project named oslc4j-fmi, so you can run the development mode Tomcat with do nothing. However, you can edit the configuration in oslc4j-fmi/conf/fmi/conf/conf.properties if you want to change the location of FMU files.
com.modelon.oslc.adapter.fmi
/conf
/fmi
/bin/* (Binary of FMIClient on each platform)
/conf/conf.properties (Configuration file)
/fmu/*.fmu (FMU files)
/temp/* (FMU unzipped files)
In configuring the adapter on production using a standalone Tomcat server, the installation is similar to the Development Mode Tomcat but the configuration directory is located in the Tomcat Installation Directory.
<Tomcat Installation Directory>
/bin (Tomcat bin folder)
/lib (Tomcat lib folder)
/logs (Tomcat logs folder)
/temp (Tomcat temp folder)
/work (Tomcat work folder)
/webapps (Tomcat webapps folder)
/oslc4jfmi.war (The deployment package of OSLC FMI adapter)
/conf (The configuration of OSLC FMI adapter)
/fmi
/bin/* (Binary of FMIClient on each platform)
/conf/conf.properties (Configuration file)
/fmu/*.fmu (FMU files)
/temp/* (FMU unzipped files)
The OSLC FMI adapter will lookup the location of FMU files in a config file named conf.properties. The configuration contains only one variable.
repository = {Location of FMU repository directory}
Default value: conf/fmi/fmu/ Post-conditions: * the value will be used to look up the location of FMU files
- Launch your web browser
- In the URL field, If you are running the adapter with Development Mode Tomcat, type http://localhost:8686/oslc4jfmi/services/catalog . If you are running the adapter with Production Mode Tomcat using port 8080, type http://localhost:8080/oslc4jfmi/services/catalog . This will send a HTTP GET request to retrieve the HTML representation of the FMI Service Provider Catalog.
- You will then see an HTML page showing you the list of Service Providers. You can browse from the Service Providers to the Services and ultimately to the OSLC FMU resources.
This sections requires a Rest client software to get OSLC resources in RDF. The recommended software is Postman that available to download at https://www.getpostman.com
The following testing guide uses Postman in Google Chrome browser.
- Click on the Postman icon at the top right of the Chrome browser . A new tab will open.
- In the URL field, If you are running the adapter with Development Mode Tomcat, type http://localhost:8686/oslc4jfmi/services/catalog . If you are running the adapter with Production Mode Tomcat using port 8080, type http://localhost:8080/oslc4jfmi/services/catalog .
- Click on the Headers field to the right of the URL field
- Enter Accept in the Header field and application/rdf+xml in the value field
- Click Send
- This will send a HTTP GET request to retrieve the RDF/XML representation of the sample FMU files as predefined in the configuration directory.
- In Eclipse, open the Project Explorer view. (Window -> Show View -> Project Explorer)
- Make sure the adapter is running before running JUnit test Suite. (See section 3.2.4 option 1)
- Expand the oslc4j-fmi-clients project
- Expand src/test/javaďż˝ folder
- Expand the package com.modelon.oslc.adapter.fmi.clients.tests
- Right click AllTests.java -> Run As -> JUnit Test
- This will run JUnit Test Suite in Eclipse and JUnit View will be opened and show the result after the test is completed.
- GET http://localhost:8686/oslc4jfmi/services/catalog
- GET http://:/oslc4jfmi/services/catalog
- GET http://localhost:8686/oslc4jfmi/services/serviceProviders
- GET http://:/oslc4jfmi/services/serviceProviders
- GET http://localhost:8686/oslc4jfmi/services/serviceProviders/{FMIFMU_Identifier}
- GET http://:/oslc4jfmi/services/serviceProviders/{FMIFMU_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/fmi/resourceShapes
- GET http://:/oslc4jfmi/services/fmi/resourceShapes
- GET http://localhost:8686/oslc4jfmi/services/rdfvocabulary
- GET http://:/oslc4jfmi/services/fmi/rdfvocabulary
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/FMU
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/FMU/{FMU_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ModelDescription
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ModelDescription/{ModelDescription_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/DefaultExperiment
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/DefaultExperiment/{DefaultExperiment_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ModelExchange
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ModelExchange/{ModelExchange_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/CoSimulation
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/CoSimulation/{CoSimulation_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/SourceFile
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/SourceFile/{SourceFile_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/UnitDefinition
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/UnitDefinition/{UnitDefinition_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/BaseUnit
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/BaseUnit/{BaseUnit_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/BaseUnitDefinition
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/BaseUnitDefinition/{BaseUnitDefinition_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/VendorAnnotation
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/VendorAnnotation/{VendorAnnotation_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/VendorTool
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/VendorTool/{VendorTool_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/Annotation
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/Annotation/{Annotation_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/TypeDefinition
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/TypeDefinition/{TypeDefinition_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/TypeDef
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/TypeDef/{TypeDef_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/Enumeration
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/Enumeration/{Enumeration_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ModelVariables
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ModelVariables/{ModelVariables_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ScalarVariable
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ScalarVariable/{ScalarVariable_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ScalarVariableType
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ScalarVariableType/{ScalarVariableType_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ListingAlias
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ListingAlias/{ListingAlias_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ListingDirectDependency
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ListingDirectDependency/{ListingDirectDependency_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/ModelStructure
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/ModelStructure/{ModelStructure_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/Derivative
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/Derivative/{Derivative_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/InitialUnknown
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/InitialUnknown/{InitialUnknown_Identifier}
- GET http://localhost:8686/oslc4jfmi/services/{FMIFMU_Identifier}/Output
- GET http://:/oslc4jfmi/services/{FMIFMU_Identifier}/Output/{Output_Identifier}
The OSLC FMI adapter utilize code from third party libraries. The respective copyright information and licenses are listed below.
The third party libraries for OSLC FMI adapter runtime
Eclipse Public License and the Eclipse Distribution License :
OSLC4J Core 3.0.0-SNAPSHOT
https://github.com/eclipse/lyo.core
OSLC4J JSON4J Provider 3.0.0-SNAPSHOT
https://github.com/eclipse/lyo.core/tree/master/org.eclipse.lyo.oslc4j.provider.json4j
OSLC4J Jena Provider 3.0.0-SNAPSHOT
https://github.com/eclipse/lyo.core/tree/master/org.eclipse.lyo.oslc4j.provider.jena
OSLC4J Query 3.0.0-SNAPSHOT
https://github.com/eclipse/lyo.core/tree/master/org.eclipse.lyo.core.query
OSLC4J Wink Application 3.0.0-SNAPSHOT
https://github.com/eclipse/lyo.core/blob/master/org.eclipse.lyo.oslc4j.wink/pom.xml
CDDL 1.0:
javax.ws.rs 1.1.1
https://jsr311.java.net
The Apache Software License, Version 2.0:
Jackson-annotations 2.7.0
https://github.com/FasterXML/jackson
Jackson-core 2.7.0
https://github.com/FasterXML/jackson-core
Jackson-databind 2.7.0
https://github.com/FasterXML/jackson-databind
The library for OSLC FMI adapter C interface runtime
BSD License:
FMILibrary 2.0.2b3
http://www.jmodelica.org/FMILibrary