You are on page 1of 9

Simulink Projects Source Control

Adapter Software Development Kit
SDK Version 2.0 for R2014a

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 .................................................................................................................................. 9
Jar Dependencies........................................................................................................................... 9

© 2011-2015 The MathWorks, Inc

The zip-file is located in (matlabroot)/toolbox/shared/cmlink/adapterSDK/cm_adapter_SDK.mathworks.version.'toolbox'. REQUIREMENTS The use of this SDK requires version 1. Sandbox: a folder containing a working copy of files copied out of a source control repository.r14a API. and CMAdapterFactory.'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. The SDK consists of two parts: this document. Matlabroot: the folder where MATLAB is installed.  Example source code for an Apache™ Subversion® (SVN) source control adapter.  JUnit tests to validate your source control adapter. This API contains all of the Java interfaces you need to implement to produce a source control adapter for the Simulink Project.'adapterSDK'. Repository: a location where files are stored when they are under the control of a source control tool. Inc . Use this example to guide you in creating your own integration with the Simulink Project (To compile and run this example you will need A JUnit 4 or greater jar file and installation of SVN 1.zip To extract the contents of the SDK you can run the MATLAB command >> run(fullfile(matlabroot. CMLINK API Interfaces The Simulink Project interacts with an external source control system through three Java interfaces: CMAdapter.7 of the Oracle® JDK. CMRepository.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.7). which can all be found in the package © 2011-2015 The MathWorks.cmlink.'shared'. and a zip-file containing  Javadoc™ for the com. Find the location of your MATLAB root by running the command matlabroot at the MATLAB command line.'cmlink’.  Files for use with the MATLAB® programming language that can assist with building and testing a source control adapter.

The 11b API provides compatibility from 11b onwards.  Providing details about the source control tool an integration is being provided for. are handled through this interface. deleting files. check out files from a repository. See the next section. where a valid sandbox doesn’t need to exist. reverting files etc.  Instances of CMRepository are produced by CMAdapterFactory instances. adding files.api.  Instances of CMAdapter are produced by CMAdapterFactory instances. committing files. CMAdapter  All sandbox level actions are done through this interface.  The Simulink Project loads all implementations of CMAdapterFactory that are registered using an OSGi Manifest in their Jar file. CMInteractor Both the CMAdapter and CMRepository interfaces extend the CMInteractor interface. Note. and how the interfaces fit together. You need to implement all three interfaces in order to create a source control adapter. Implementing the buildCustomActions method enables buttons and labels to be added to the Simulink Project’s source control UIs. These interfaces are for the 11b version of the API. updating files. CMRepository  All repository level actions. a set of interfaces with the same name can be found in the package cmlink. This interface handles the following functionality:  Connection handling (optional)  Custom action creation.api. Inc . CMAdapterFactory  Instantiates CMAdpater and CMRepository instances  An implementation of CMAdapter factory determines whether a specified folder. rather than an instance of CMRepository. For example.version. CMAdapterFactory. but does not allow the creation of custom widgets or facilitate the reporting of exceptions in the project’s UI.  This provides functionality to create a sandbox. and its sub-folders.  If only sandbox level integration is to be provided by the source control adapter the method getRepository can return null.r14a. etc. These interfaces are compatible with version 14a of MATLAB and above.  Implementing this interface is optional.  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. can be controlled by this source control tool. © 2011-2015 The MathWorks.cmlink. This section provides an overview of the role of the interfaces you need to implement.

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.Relationship between interfaces in cmlink. In this case it will be up to the user of Simulink Projects to choose the adapter they want to © 2011-2015 The MathWorks. It does this by asking each source control adapter. You need to familiarise yourself with the Java interfaces in the package com.api.api.api. This jar file will be required when setting up your development environment.mathworks. It is possible for multiple CMAdapterFactory implementations to state that they can manage a given folder. This is done through the isDirSandboxForThisAdapter method of com.cmlink.cmlink.CMAdapter for the specified folder.mathworks.mathworks.Figure 1 . This is done using the getAdapterForThisSandboxDir method of CMAdapterFactory.version. 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.r14a Javadoc For more information on each interface. Inc . matlabroot is described in the Terminology section.api.jar.cmlink. whether or not it can manage that project root folder. 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. through its CMAdapterFactory implementation.CMAdapterFactory. refer to the Javadoc supplied with the SDK in the Javadoc folder.

To support a feature. such as move for the MOVE member of AdapterSupportedFeature..CMAdapterFactory.api. which are described below. Supported Features Source control adapters can implement a sub-set of the full functionality of the API. CMAdapter Supported Features The interface CMAdapter has the method boolean isFeatureSupported(AdapterSupportedFeature feature) where AdapterSupportedFeature is an enumeration. and the relevant CMAdapterFactory will be called upon to provide a CMAdapter instance.api interface on the MATLAB Java class-path. via existing features of the Simulink Project user interface. To ensure your adapter implementation is detectable requires the following: 1. Inc . CMInteractor Supported Features The interface CMInteractor has the method boolean isFeatureSupported(InteractorSupportedFeature feature) where InteractorSupportedFeature is an enumeration.cmlink. © 2011-2015 The MathWorks. Each member of this enumeration represents a supported feature. The class files must be stored in a jar file.use. This enables the MATLAB OSGi server to instantiate all available CMAdapterFactory implementations. Each member of this enumeration represents a supported feature. 2. Manifest The Simulink Project uses OSGi to detect implementations of the com. There are three supported feature enumerations which are detailed below. Each member of this enumeration represents a supported feature. This is done through “supported features” enumerations. will not be called by the Simulink Project if they are not supported by the implementation. The manifest file in your jar file must declare which class implements the interface cmlink. the implementation of CMAdapter should return true for the appropriate member of AdapterSupportedFeature. The Javadoc for AdapterSupportedFeature describes each individual feature.mathworks. CMRespository Supported Features The interface CMRepository has the method boolean isFeatureSupported(RepositorySupportedFeature feature) where RepositorySupportedFeature is an enumeration. The methods that implement a supported feature.

mathworks.txt should contain one line for each jar file being added to the classpath.cmlink.'javaclasspath.cmlink Bundle-Description: Provides CM functionality Bundle-Vendor: The MathWorks.svnintegration.sdk.ServicesActivator Services: com.mathworks.r14a.util. build. is included in the SDK. Inc.osgi. Add the following lines to the manifest of your jar file: Bundle-Name: CMAdapter MathWorks-Bundle: true Bundle-SymbolicName: com.SVNAdapterFactory where SVNAdapterFactory exists in the Jar file containing the manifest. MATLAB’s java classpath can be augmented by putting a file called javaclasspath. This interface provides the following functionality:  Instantiates a CMAdapterFactory  Creates a test repository  Creating a sandbox given a repository specifier String. This build script creates a valid OSGi manifest for the jar file it creates.version. Each line should consist of the fully qualified file location of the adapter’s jar file.txt in MATLAB’s preference folder.txt')).xml.mathworks. You must restart MATLAB for changes in the Java classpath to take effect. To create or edit this file you type the following at the MATLAB command line. Note An Apache Ant™ build script. javaclasspath. edit(fullfile(prefdir.0. JUnit Tests The SDK includes a JUnit test class that you can use to test new source control adapters.cmlink.CMAdapterFactory: <package qualified class name of implementation> An example of a valid substitution of <package qualified class name of implementation> would be com. © 2011-2015 The MathWorks. See the Section “Building with Ant”.3. 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. Inc . MATLAB Classpath After building. To find this folder type prefdir at the MATLAB command line. Bundle-Version: 1.0 Bundle-Activator: com. In order to test an implementation the JUnit test class must be constructed with an implementation of CMTestEnvironment.api.mathworks.example.

Version 1. Source Code The source code for the JUnit test is in the folder src/com/mathworks/cmlink/sdk/tests/ of the SDK folder.apache. as follows: public class TSVNAdapter extends TAdapter { public TSVNAdapter() throws Exception { super( new SVNTestEnvironment()). This is expected and passing this test is not required for creating a Simulink Project source control adapter for a locking source control. then you can use your source control adapter with Simulink Projects.jar) to the top level of the SDK folder. provided with this SDK. } } The next section describes how to execute this example test using an ant script provided with the SDK. You can download both files here: http://junit.8 of Ant was used to create this script. An Ant build (build. To supply the CMTestEnviroment to the JUnit class TAdapter. 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. you need to extend TAdapter and implement a zero argument constructor which calls super with an instance of CMTestEnvironment.org/bindownload. Inc . You can see how this is done in the SVN example.See the Javadoc for more details. You can download Ant here: http://ant.xml) script for the example SVN implementation is in the root folder of the SDK. you need to copy a JUnit 4 jar file (junit.jar) and hamcres jar file (hamcrest.testConflictResolution(). Jar Dependencies The JUnit test TAdapter. Build your own interfaces using this example as a guide. To run the JUnit test using this script.cgi.jar <matlabroot>/java/jar/cmlink/util. Building with Ant You need to install Apache Ant before you can use the build script.org.java has the following dependencies <matlabroot>/java/jar/cmlink/api.jar Locking CM Systems Locking source control systems will fail the test TAdapter. © 2011-2015 The MathWorks.

you must change MATLAB’s current folder to be the root folder of the SDK folder. containing the example adapter: <sdk-root>\jar\svnIntegration. 3. 3.Note To run the ant script from MATLAB. 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. ant –Dmatlab=<matlabroot> compile. enter ‘edit classpath.jar.showProject at the MATLAB command line.ModelManagement. rather than inside MATLAB.txt’. After installing Ant.jar – contains SVN example configures tests in testBase. At the MATLAB command line. e.txt file.jar – Contains cmlink JUnit tests.  Entering Simulink. Inc . 2. © 2011-2015 The MathWorks. Restart MATLAB to refresh the classpath. To run the ant script from the command line. 2.  To get live information on the currently running tests use: ant junit -verbose  ant clean o Deletes any compiled jar files. 4. the MATLAB root must be specified.  testSVN. Save and close the classpath.jar You need to add this jar to the MATLAB classpath before MATLAB can use it. Using the Example Adapter in MATLAB When you run ‘ant compile’. Check that the example SVN source control adapter is available in the list of source control adapters. Select the menu: Simulink Project -> Retrieve from Source Control. you create the following file. Add an entry to the classpath file which is the full file path of the jar file: <sdk- root>\jar\svnIntegration.jar to be run by SVN adapter code.  svnIntegration.jar.jar – Contains SVN Simulink Project Adapter  ant runTests o Runs the JUnit unit tests found in testSVN. 1.g. To verify that the adapter is detected by the Simulink Project: 1. Open the Simulink Project by either:  Loading a Simulink model and selecting View->Simulink Project. Add the switch –Dmatlab=<matlab install location>. where <sdk-root> is the location of the cmlink SDK folder.

jar file.jar  <matlabroot>/java/jarext/commons-io.jar  <matlabroot>/java/jar/mwswing.jar  <matlabroot>/java/jar/widgets.jar The example SVN adapter requires the following jar files. © 2011-2015 The MathWorks. Inc .jar  <matlabroot>/java/jar/toolbox/slproject.Source Code The source code for the example is in the src/com/mathworks/cmlink/sdk/example folder of the SDK folder.jar The test TSVNAdapter.jar  <matlabroot>/java/jar/cmlink/util.jar  <matlabroot>/java/jar/util.  <matlabroot>/java/jar/cmlink/api.java also requires a JUnit 4 junit.jar file and hamcrest. Jar Dependencies All cmlink integrations must link against the interfaces found in the jar file:  <matlabroot>/java/jar/cmlink/api.