Magic Square Example: MATLAB Programmer Tasks

On this page…
Copying the Example Files Testing the MATLAB File You Want to Deploy Creating the Magic Square Java Component Packaging the Magic Square Java Component (Optional) Copy the Package You Created (Optional)

MATLAB Programmer

Role	Knowledge Base	Responsibilities
MATLAB programmer	MATLAB expert No IT experience No access to IT systems	Develops models; implements in MATLAB Uses tools to create a component that is used by the Java developer

The following tasks are usually performed by the MATLAB programmer.

Key Tasks for the MATLAB Programmer

Task	Reference
Prepare to run the example by copying the MATLAB example files into a work folder.	Copying the Example Files
Test the MATLAB code to ensure it is suitable for deployment.	Testing the MATLAB File You Want to Deploy
Create a Java package (encapsulating your MATLAB code in a Java class) by running the Build function in deploytool.	Creating the Magic Square Java Component
Run the Packaging Tool to bundle your Java component with the additional files you selected.	Packaging the Magic Square Java Component (Optional)
Copy the output from the Packaging Tool (the distrib folder).	Copy the Package You Created (Optional)

Copying the Example Files

Prepare to run the example by copying needed files into your work area as follows:

1. Navigate to matlabroot\toolbox\javabuilder\Examples\MagicSquareExample. matlabroot is the MATLAB root folder (where MATLAB is installed). To find the value of this variable on your system, type matlabroot at a command prompt.

2. Copy the MagicSquareExample folder to a work area, for example, D:\javabuilder_examples. Avoid using spaces in your folder names, if possible. The example files should now reside in D:\javabuilder_examples\MagicSquareExample.

3. Using a command prompt, navigate to D:\javabuilder_ examples\MagicSquareExample by switching to the D: drive and entering cd \javabuilder_examples\MagicSquareExample.

Back to Top

Testing the MATLAB File You Want to Deploy

Normally you would first create the MATLAB file you want to deploy. In this example, you will test a precreated MATLAB file (makesqr.m) containing the predefined MATLAB function magic.

1. Using MATLAB, locate the makesqr.m file at D:\javabuilder_examples\MagicSquareExample\MagicDemoComp. The contents of the file are as follows:

   function y = makesqr(x)
   %MAKESQR Magic square of size x.
   %   Y = MAKESQR(X) returns a magic square of size x.
   %   This file is used as an example for the MATLAB 
   %   Builder JA product.
   
   %   Copyright 2001-2010 The MathWorks, Inc.
   
   y = magic(x);

2. At the command prompt, enter makesqr(5) and view the results. The output should appear as follows:

   17 24  1  8 15
   23  5  7 14 16
    4  6 13 20 22
   10 12 19 21  3
   11 18 25  2  9

Back to Top

Creating the Magic Square Java Component

You create the Magic Square Java application by using the Deployment Tool GUI to build a Java class that wraps around the sample MATLAB code discussed in Testing the MATLAB File You Want to Deploy.

Use the following information as you work through this example using the instructions in Building the Java Component:

Project Name	magicsquare
Class Name	magic
File to compile	makesqr.m

What Happens in the Build Process

Note   The MATLAB Builder JA product uses the JAVA_HOME variable to locate the Java Software Development Kit (SDK) on your system. The compiler uses this variable to set the version of the javac.exe command it uses during compilation.

To create a component, the builder does the following:

1. Generates Java code to implement your component. The files are as follows:

   myclass.java	Contains a Java class with methods encapsulating the MATLAB functions specified in the project for that class.
   mycomponentMCRFactory.java	Java component with first character of mycomponent capitalized.
   myclassremote.java	Contains a remotable Java class with methods encapsulating the MATLAB functions specified in the project for that class. See Creating Scalable Web Applications Using RMI.
   package-info.java	Javadoc package documentation.

2. Compiles the Java code produced in step 1.

3. Generates /distrib and /src subfolders.

4. Invokes the Jar utility to package the Java class files it has created into a Java archive file (mycomponent.jar).

For information about how MATLAB Compiler works, see How Does MATLAB Compiler Software Build My Application?.

Anatomy of a MATLAB Builder JA Project

A builder project contains information about the files and settings needed by the MATLAB Builder JA product to create a deployable Java component. A project specifies information about classes and methods, including the MATLAB functions to be included.

Classes and Methods .  The builder transforms MATLAB functions that are specified in the component's project to methods belonging to a Java class.

When creating a component, you must provide one or more class names as well as a component name. The class name denotes the name of the class that encapsulates MATLAB functions.

To access the features and operations provided by the MATLAB functions, instantiate the Java class generated by the builder, and then call the methods that encapsulate the MATLAB functions.

Note   When you add files to a project, you do not have to add any MATLAB files for functions that are called by the functions that you add. When the MATLAB Builder JA product builds a component, it automatically includes any MATLAB functions called by the functions that you explicitly specify for the component. See the Spectral Analysis Example for a sample application that illustrates this feature.

Naming Conventions.  Typically you should specify names for components and classes that will be clear to programmers who use your components. For example, if you are encapsulating many MATLAB functions, it helps to determine a scheme of function categories and to create a separate class for each category. Also, the name of each class should be descriptive of what the class does.

Valid characters are any alpha or numeric characters, as well as the underscore (_) character.

Back to Top

Packaging the Magic Square Java Component (Optional)

Bundling the Java component with additional files into a JAR file that can be distributed to users is called packaging. You will perform this step using the packaging function of deploytool. Alternately, copy the contents of the distrib folder and the MCR Installer to a local folder of your choice. If you are creating a shared component and want to include additional code with the component, you must perform this step.

Note   "Packaging" a component and a "Java package" are different concepts. "Packaging" in this context refers only to the act of using MATLAB Builder JA to bundle the Java component with associated files needed to successfully deploy the application. A "Java package" is a collection of Java classes and methods.

1. On the Package tab, add the MATLAB Compiler Runtime (MCR). To do so, click Add MCR, and choose one of the two options described in the following table.

   Option	What Does This Option Do?	When Should I Use This Option?
   Embed the MCR in the package	This option physically copies the MCR Installer file into the package you create.	You have a limited number of end users who deploy a small number of applications at sporadic intervals Your users have no intranet/network access Resources such as disk space, performance, and processing time are not significant concerns Note   Distributing the MCR Installer with each application requires more resources.
   Invoke the MCR from a network location	This option lets you add a link to an MCR Installer residing on a local area network, allowing you to invoke the installer over the network, as opposed to copying the installer physically into the deployable package. This option sets up a script to install the MCR from a specified network location, saving time and resources when deploying applications.	You have a large number of end users who deploy applications frequently Your users have intranet/network access Resources such as disk space, performance, and processing time are significant concerns for your organization If you choose this option, modify the location of the MCR Installer, if needed. To do so, select the Preferences link in this dialog box, or change the Compiler option in your MATLAB Preferences. Caution   Before selecting this option, consult with your network or systems administrator. Your administrator may already have selected a network location from which to run the MCR Installer.

   For more information about the role the MCR plays in the deployment process, see Installing the MATLAB Compiler Runtime (MCR).

2. Next, add others files you feel may be useful to end users. To package additional files or folders, click Add file/directories, select the file or folder you want to package, and click Open.

3. In the Deployment Tool, click the Packaging button ( ).

4. For Windows, the package is a self-extracting executable. On platforms other than Windows, the package is delivered as a .zip file. Verify that the contents of the distrib folder contains the files you specified.

What Happens in the Packaging Process?

The packaging process creates a self-extracting executable (on Windows platforms) or a .zip file (on platforms other than Windows). The package contains at least the following:

• The builder component

• The MCR Installer (if the Install MCR option was selected when the component was built)

• Documentation generated by the Sun Microsystems Javadoc tool

Note   The packaging process is not available when using mcc directly.

Note   For guidelines on multi-platform portability, reference Ensuring Multi-Platform Portability.

How Does the MATLAB Builder JA Product Use JAR Files?

As of R2007b, the MATLAB Builder JA product now embeds the CTF archive within the generated JAR file, by default. This offers convenient deployment of a single output file since all encrypted MATLAB file data is now contained within this Java archive.

For information on CTF archive data extraction and utilization using MWComponentOptions see Using MCR Component Cache and MWComponentOptions.

Back to Top

Copy the Package You Created (Optional)

Copy the package that you created from the distrib folder to the local folder of your choice or send them directly to the Java developer.

Back to Top

The Magic Square Example

Magic Square Example: Java Developer Tasks

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS