Simulink Projects Source Control

Adapter Software Development Kit

SDK Version 1.2 for R2013b, March 2013

Contents
Introduction ............................................................................................................................................ 2
Terminology ........................................................................................................................................ 2
REQUIREMENTS ...................................................................................................................................... 2
CMLINK API ............................................................................................................................................. 2
Interfaces ............................................................................................................................................ 2
Javadoc................................................................................................................................................ 4
Jar Dependencies ................................................................................................................................ 4
Sandbox Detection .............................................................................................................................. 4
Supported Features ............................................................................................................................ 5
Manifest .............................................................................................................................................. 5
MATLAB Classpath .......................................................................................................................... 6
JUnit Tests ............................................................................................................................................... 6
Source Code ........................................................................................................................................ 7
Jar Dependencies ................................................................................................................................ 7
Locking CM Systems ............................................................................................................................ 7
Example Source Control Adapter ............................................................................................................ 7
Building with Ant................................................................................................................................. 7
Using the Example Adapter in MATLAB .......................................................................................... 8
Source Code ........................................................................................................................................ 8
Jar Dependencies ................................................................................................................................ 9

2011-2013 The MathWorks, Inc

Introduction
You can use this Software Development Kit (SDK) to integrate Simulink Projects with a source
control tool that has a published API that can be called from Java. You must create a jar file which
implements a collection of Java interfaces and a Java Manifest file which defines a set of required
properties.
The SDK consists of two parts: this document, and a zip-file containing

Javadoc for the com.mathworks.cmlink API. This API contains all of the Java interfaces you
need to implement to produce a source control adapter for the Simulink Project.
JUnit tests to validate your source control adapter.
Example source code for an Apache Subversion (SVN) source control adapter. Use this
example to guide you in creating your own integration with the Simulink Project.
Files for use with the MATLAB programming language that can assist with building and
testing a source control adapter.

The zip-file is located in

(matlabroot)/toolbox/shared/cmlink/adapterSDK/cm_adapter_SDK.zip
To extract the contents of the SDK you can run the MATLAB command
>> run(fullfile(matlabroot,'toolbox','shared','cmlink,'adapterSDK','extractSDK'))

Terminology
Within this SDK we use the following terms:
Adapter: the software that provides an interface between an external source control tool and
Simulink projects.
Repository: a location where files are stored when they are under the control of a source control
tool.
Sandbox: a folder containing a working copy of files copied out of a source control repository.
Matlabroot: the folder where MATLAB is installed. Find the location of your MATLAB root by
running the command matlabroot at the MATLAB command line.

REQUIREMENTS
The use of this SDK requires version 1.7 of the Oracle JDK.

CMLINK API
Interfaces
The Simulink Project interacts with an external source control system through three Java interfaces:
CMAdapter, CMRepository, and CMAdapterFactory. You need to implement all three interfaces in

2011-2013 The MathWorks, Inc

order to create a source control adapter. This section provides an overview of the role of the
interfaces you need to implement, and how the interfaces fit together.
CMAdapter
All sandbox level actions are done through this interface. For example, adding files, deleting
files, updating files, committing files, reverting files etc.

It is called CMAdapter because it provides an Adapter layer between a source control tool
and a common interface which can be used by the Simulink Project.

Instances of CMAdapter are produced by CMAdapterFactory instances.

CMRepository
All repository level actions, where a valid sandbox doesnt need to exist, are handled
through this interface.

This provides functionality to create a sandbox, check out files from a repository, etc.

Instances of CMRepository are produced by CMAdapterFactory instances.

Implementing this interface is optional. See the next section, CMAdapterFactory.

CMAdapterFactory
Instantiates CMAdpater and CMRepository instances

An implementation of CMAdapter factory determines whether a specified folder, and its

sub-folders, can be controlled by this source control tool.

The Simulink Project loads all implementations of CMAdapterFactory that are registered
using an OSGi Manifest in their Jar file.

If only sandbox level integration is to be provided by the source control adapter the method
getRepository() can return null, rather than an instance of CMRepository.

CMInteractor
Both the CMAdapter and CMRepository interfaces extend the CMInteractor interface. This interface
handles user interaction with MATLAB, such as:

Progress reporting
Cancellation
Status change events
Version information
Connection handling (optional)

2011-2013 The MathWorks, Inc

Figure 1 - Relationship between interfaces in cmlink.api.

Javadoc
For more information on each interface, refer to the Javadoc supplied with the SDK in the Javadoc
folder. You need to familiarise yourself with the Java interfaces in the package
com.mathworks.cmlink.api. You can find the Javadoc for this package in the SDK in the top level
folder Javadoc.

Jar Dependencies
These interfaces are declared in the jar file <matlabroot>/java/jar/cmlink/api.jar. This jar file will be
required when setting up your development environment. matlabroot is described in the
Terminology section.

Sandbox Detection
The Simulink Project needs to know which Source Control adapters are suitable for managing the
files within the root folder of a project. It does this by asking each source control adapter, through its
CMAdapterFactory implementation, whether or not it can manage that project root folder. This is
done through the isDirSandboxForThisAdapter method of
com.mathworks.cmlink.api.CMAdapterFactory.
If a CMAdapterFactory states that it can handle source control operations for a specified folder then
the Simulink Project will request the CMAdapterFactory to produce an implementation of
com.mathworks.cmlink.api.CMAdapter for the specified folder. This is done using the
getAdapterForThisSandboxDir method of CMAdapterFactory.
It is possible for multiple CMAdapterFactory implementations to state that they can manage a given
folder. In this case it will be up to the user of Simulink Projects to choose the adapter they want to

2011-2013 The MathWorks, Inc

use, via existing features of the Simulink Project user interface, and the relevant CMAdapterFactory
will be called upon to provide a CMAdapter instance.

Supported Features
Source control adapters can implement a sub-set of the full functionality of the API. This is done
through supported features enumerations, which are described below. There are three supported
feature enumerations which are detailed below.
CMAdapter Supported Features
The interface CMAdapter has the method
boolean isFeatureSupported(AdapterSupportedFeature feature)
where AdapterSupportedFeature is an enumeration. Each member of this enumeration represents a
supported feature. To support a feature, the implementation of CMAdapter should return true for
the appropriate member of AdapterSupportedFeature. The Javadoc for AdapterSupportedFeature
describes each individual feature. The methods that implement a supported feature, such as move
for the MOVE member of AdapterSupportedFeature, will not be called by the Simulink Project if they
are not supported by the implementation.
CMRespository Supported Features
The interface CMRepository has the method
boolean isFeatureSupported(RepositorySupportedFeature feature)
where RepositorySupportedFeature is an enumeration. Each member of this enumeration
represents a supported feature.
CMInteractor Supported Features
The interface CMInteractor has the method
boolean isFeatureSupported(InteractorSupportedFeature feature)
where InteractorSupportedFeature is an enumeration. Each member of this enumeration represents
a supported feature.

Manifest
The Simulink Project uses OSGi to detect implementations of the com.mathworks.cmlink.api
interface on the MATLAB Java class-path. To ensure your adapter implementation is detectable
requires the following:
1. The class files must be stored in a jar file.

2. The manifest file in your jar file must declare which class implements the interface
cmlink.api.CMAdapterFactory.. This enables the MATLAB OSGi server to instantiate all available
CMAdapterFactory implementations.
2011-2013 The MathWorks, Inc

3. Add the following lines to the manifest of your jar file:

Bundle-Name: CMAdapter
MathWorks-Bundle: true
Bundle-SymbolicName: com.mathworks.cmlink
Bundle-Description: Provides CM functionality
Bundle-Vendor: The MathWorks, Inc.
Bundle-Version: 1.0.0
Bundle-Activator: com.mathworks.util.osgi.ServicesActivator
Services: com.mathworks.cmlink.api.CMAdapterFactory: <package qualified class name
of implementation>

An example of a valid substitution of <package qualified class name of implementation> would be

com.mathworks.cmlink.sdk.example.svnintegration.SVNAdapterFactory where SVNAdapterFactory
exists in the Jar file containing the manifest.
Note
An Apache Ant build script, build.xml, is included in the SDK. This build script creates a valid OSGi
manifest for the jar file it creates. See the Section Building with Ant.
MATLAB Classpath
After building, you must add the jar file containing the source control adapter to the MATLAB Java
classpath in order to use it in the Simulink Project.
MATLABs java classpath can be augmented by putting a file called javaclasspath.txt in MATLABs
preference folder. To find this folder type prefdir at the MATLAB command line.
To create or edit this file you type the following at the MATLAB command line.
edit(fullfile(prefdir,'javaclasspath.txt'));
javaclasspath.txt should contain one line for each jar file being added to the classpath. Each line
should consist of the fully qualified file location of the adapters jar file.
You must restart MATLAB for changes in the Java classpath to take effect.

JUnit Tests
The SDK includes a JUnit test class that you can use to test new source control adapters.
In order to test an implementation the JUnit test class must be constructed with an implementation
of CMTestEnviornment.
This interface provides the following functionality:

Instantiates a CMAdapterFactory
Creates a test repository
Creating a sandbox given a repository specifier String.

2011-2013 The MathWorks, Inc

See the Javadoc for more details.

To supply the CMTestEnviroment to the JUnit class TAdapter, you need to extend TAdapter and
implement a zero argument constructor which calls super with an instance of CMTestEnvironment.
You can see how this is done in the SVN example, provided with this SDK, as follows:
public class TSVNAdapter extends TAdapter {
public TSVNAdapter() throws Exception {
super( new SVNTestEnvironment());
}
}

The next section describes how to execute this example test using an ant script provided with the
SDK.

Source Code
The source code for the JUnit test is in the folder src/com/mathworks/cmlink/sdk/tests/ of the SDK
folder.

Jar Dependencies
The JUnit test TAdapter.java has the following dependencies
<matlabroot>/java/jar/cmlink/api.jar
<matlabroot>/java/jar/cmlink/util.jar

Locking CM Systems
Locking source control systems will fail the test TAdapter.testConflictResolution(). This is expected
and passing this test is not required for creating a Simulink Project source control adapter for a
locking source control.

Example Source Control Adapter

The SDK includes an example SVN implementation. The following instructions describe how to build
the example and use it with Simulink Projects. Build your own interfaces using this example as a
guide, then you can use your source control adapter with Simulink Projects.

Building with Ant

You need to install Apache Ant before you can use the build script. You can download Ant here:
http://ant.apache.org/bindownload.cgi.
An Ant build (build.xml) script for the example SVN implementation is in the root folder of the SDK.
Version 1.8 of Ant was used to create this script.
To run the JUnit test using this script, you need to copy a JUnit 4 jar file to the top level of the SDK
folder. You can download JUnit here: https://github.com/KentBeck/junit/downloads.
Note
To run the ant script from MATLAB, you must change MATLABs current folder to be the root folder
of the SDK folder.
2011-2013 The MathWorks, Inc

To run the ant script from the command line, rather than inside MATLAB, the MATLAB root must be
specified. Add the switch Dmatlab=<matlab install location>.
e.g. ant Dmatlab=<matlabroot> compile.
After installing Ant, you can use the following commands at the command line or within MATLAB in
the root sdk folder:

ant compile
o Compiles the sources in sdk/src to jar files
testBase.jar Contains cmlink JUnit tests.
testSVN.jar contains SVN example configures tests in testBase.jar to be run
by SVN adapter code.
svnIntegration.jar Contains SVN Simulink Project Adapter
ant runTests
o Runs the JUnit unit tests found in testSVN.jar.
To get live information on the currently running tests use:
ant junit -verbose
ant clean
o Deletes any compiled jar files.

Using the Example Adapter in MATLAB

When you run ant compile, you create the following file, containing the example adapter:
<sdk-root>\jar\svnIntegration.jar
You need to add this jar to the MATLAB classpath before MATLAB can use it.
1. At the MATLAB command line, enter edit classpath.txt.
2. Add an entry to the classpath file which is the full file path of the jar file: <sdkroot>\jar\svnIntegration.jar, where <sdk-root> is the location of the cmlink SDK folder.
3. Save and close the classpath.txt file.
To verify that the adapter is detected by the Simulink Project:
1. Restart MATLAB to refresh the classpath.
2. Open the Simulink Project by either:
Loading a Simulink model and selecting View->Simulink Project.
Entering Simulink.ModelManagement.showProject at the MATLAB command line.
3. Select the menu: Simulink Project -> Retrieve from Source Control.
4. Check that the example SVN source control adapter is available in the list of source control
adapters.

Source Code
The source code for the example is in the src/com/mathworks/cmlink/sdk/example folder of the SDK
folder.

2011-2013 The MathWorks, Inc

Jar Dependencies
All cmlink integrations must link against the interfaces found in the jar file:
<matlabroot>/java/jar/cmlink/api.jar
The example SVN adapter requires the following jar files.
<matlabroot>/java/jar/cmlink/api.jar
<matlabroot>/java/jar/cmlink/util.jar
<matlabroot>/java/jar/toolbox/slproject.jar
<matlabroot>/java/jar/util.jar
<matlabroot>/java/jar/mwswing.jar
<matlabroot>/java/jar/widgets.jar
<matlabroot>/java/jarext/commons-io.jar
The test TSVNAdapter.java also requires a JUnit 4 JUnit.jar file.

2011-2013 The MathWorks, Inc