Simulink

Projects Source Control Adapter Software Development Kit

SDK Version 1.1 for R2011b, December 2012

Contents
Introduction ...................................................................................................................................... 2 Terminology .................................................................................................................................. 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-2012 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/simulink/simulink/slproject/adapterSDK/cm_adapter_SDK.zip To extract the contents of the SDK you can run the MATLAB command >> run(fullfile(matlabroot,'toolbox','simulink','simulink','slproject','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.

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 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.

2011-2012 The MathWorks, Inc

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-2012 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-2012 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-2012 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-2012 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-2012 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-2012 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-2012 The MathWorks, Inc