MA|A88u|der" 1A 2Usors Guido How lo Conlocl Ihe
MolhWorksWWW.na1hWorks.con Webconp.sof1-sys.na1Jab
NewsgroupWWW.na1hWorks.con1con1ac1TS.h1nJ Technical
Supportsugges10na1hWorks.con Product enhancement
suggestionsbugs0na1hWorks.con Bug reportsdoc0na1hWorks.con
Documentation error reportsserv1ce0na1hWorks.con Order status,
license renewals, passcodes1nfo0na1hWorks.con Sales, pricing, and
general information508-647-7000 (Phone)508-647-7001 (Fax)The
MathWorks, Inc.3 Apple Hill DriveNatick, MA 01760-2098For contact
information about worldwide offices, see the MathWorks Web
site.MATLAB Builder JA Users Guide COPYRIGHT 20062010 by The
MathWorks, Inc.The software described in this document is furnished
under a license agreement. The software may be usedor copied only
under the terms of the license agreement. No part of this manual
may be photocopied orreproduced in any form without prior written
consent from The MathWorks, Inc.FEDERAL ACQUISITION: This provision
applies to all acquisitions of the Program and Documentationby,
for, or through the federal government of the United States. By
accepting delivery of the Programor Documentation, the government
hereby agrees that this software or documentation qualifies
ascommercial computer software or commercial computer software
documentation as such terms are usedor defined in FAR 12.212, DFARS
Part 227.72, and DFARS 252.227-7014. Accordingly, the terms
andconditions of this Agreement and only those rights specified in
this Agreement, shall pertain to and governthe use, modification,
reproduction, release, performance, display, and disclosure of the
Program andDocumentation by the federal government (or other entity
acquiring for or through the federal government)and shall supersede
any conflicting contractual terms or conditions. If this License
fails to meet thegovernments needs or is inconsistent in any
respect with federal procurement law, the government agreesto
return the Program and Documentation, unused, to The MathWorks,
Inc.IrodemorksMATLAB and Simulink are registered trademarks of The
MathWorks, Inc. SeeWWW.na1hWorks.con11radenarks for a list of
additional trademarks. Other product or brandnames may be
trademarks or registered trademarks of their respective
holders.PolenlsThe MathWorks products are protected by one or more
U.S. patents. Please seeWWW.na1hWorks.con1pa1en1s for more
information.kevision HislorySeptember 2006 Online only New for
Version 1.0 (Release 2006b)March 2007 Online only Revised for
Version 1.1 (Release 2007a)September 2007 Online only Revised for
Version 2.0 (Release 2007b)March 2008 Online only Revised for
Version 2.0.1 (Release 2008a)October 2008 Online only Revised for
Version 2.0.2 (Release 2008b)March 2009 Online only Revised for
Version 2.0.3 (Release 2009a)September 2009 Online only Revised for
Version 2.0.4 (Release 2009b)March 2010 Online only Revised for
Version 2.1 (Release 2010a)ConlenlsGetting Started1Product Overview
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-2MATLAB Compiler Extension . . . . . . . . . . . . . . . . . . .
. . . 1-2How the MATLAB Compiler and MATLAB Builder JAProducts Work
Together . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2How
Does Component Deployment Work? . . . . . . . . . . . . .
1-3Limitations of Support . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 1-3Before You Use MATLAB Builder JA . . . . . . . .
. . . . . . . 1-4Your Role in the Java Application Deployment
Process . . . 1-4What You Need to Know . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 1-6Required Products . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 1-7Configuring Your
Environment . . . . . . . . . . . . . . . . . . . . . . 1-7Quick
Start: Deploying a Component with the HelloWorld Example . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10About
the Hello World Example . . . . . . . . . . . . . . . . . . . . . .
1-10Before Running the Hello World Example . . . . . . . . . . . .
. 1-10The Hello World Example . . . . . . . . . . . . . . . . . . .
. . . . . . . . 1-10Building the Java Component . . . . . . . . . .
. . . . . . . . . . . . . 1-11Deploying Hello World On a Computer
with MATLAB,MATLAB Compiler, and MATLAB Builder JAInstalled . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 1-13Deploying Hello World On a Computer with Only theMATLAB
Compiler Runtime (MCR) Installed (MATLABNot Installed) . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-14Deploying a Component with the Magic SquareExample . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-16About This Example . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 1-16Magic Square Example: MATLAB Programmer Tasks
. . . 1-16Magic Square Example: Java Programmer Tasks . . . . . . .
1-26Next Steps . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 1-36vWriting Deployable MATLAB Code2The
MATLAB Application Deployment Products . . . . . 2-2Building Your
Application with the ApplicationDeployment Products and the
Deployment Tool . . . . 2-4What Is the Difference Between the
Deployment Tool andthe mcc Command Line? . . . . . . . . . . . . .
. . . . . . . . . . . . 2-4How Does MATLAB Compiler Software Build
MyApplication? . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 2-4What You Should Know About the Dependency
AnalysisFunction (depfun) . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 2-5Compiling MEX-Files, DLLs, or Shared
Libraries . . . . . . . 2-6The Role of the Component Technology
File (CTFArchive) . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 2-7Guidelines for Writing Deployable
MATLAB Code . . . . 2-10Compiled Applications Do Not Process MATLAB
Files atRuntime . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 2-10Do Not Rely on Changing Directory or
Path to Control theExecution of MATLAB Files . . . . . . . . . . .
. . . . . . . . . . . . 2-11Use ismcc and isdeployed Functions To
ExecuteDeployment-Specific Code Paths . . . . . . . . . . . . . . .
. . . . 2-11Gradually Refactor Applications That Depend
onNoncompilable Functions . . . . . . . . . . . . . . . . . . . . .
. . . . 2-12Do Not Create or Use Nonconstant Static StateVariables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 2-12Working with MATLAB Data Files Using Load andSave . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 2-14Using Load/Save Functions to Process MATLAB Data
forDeployed Applications . . . . . . . . . . . . . . . . . . . . .
. . . . . . 2-14Programming3About the MATLAB Builder JA API . . . .
. . . . . . . . . . . . 3-3vi ContentsUnderstanding the MATLAB
Builder JA API DataConversion Classes . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 3-3Automatic Conversion to MATLAB
Types . . . . . . . . . . . . . . 3-4Understanding Function
Signatures Generated by theMATLAB Builder JA Product . . . . . . .
. . . . . . . . . . . . . . 3-5Adding Fields to Data Structures and
Data StructureArrays . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 3-6Returning Data from MATLAB to
Java . . . . . . . . . . . . . . . . 3-7Importing Classes . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8Creating
an Instance of the Class . . . . . . . . . . . . . . . . . . .
3-9What Is an Instance? . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 3-9Code Fragment: Instantiating a Java Class . . .
. . . . . . . . . 3-9Passing Arguments to and from Java . . . . . .
. . . . . . . . . . 3-13Format . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 3-13Manual
Conversion of Data Types . . . . . . . . . . . . . . . . . . . .
3-13Automatic Conversion to a MATLAB Type . . . . . . . . . . . . .
3-14Specifying Optional Arguments . . . . . . . . . . . . . . . . .
. . . . . 3-16Handling Return Values . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 3-21Passing Java Objects by Reference . .
. . . . . . . . . . . . . . . . 3-27MATLAB Array . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 3-27Wrappering
and Passing Java Objects to MATLABFunctions with MWJavaObjectRef .
. . . . . . . . . . . . . . . . 3-27Handling Errors . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34Error
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . 3-34Handling Checked Exceptions . . . . . . . . . . . .
. . . . . . . . . . . 3-34Handling Unchecked Exceptions . . . . . .
. . . . . . . . . . . . . . . 3-37Managing Native Resources . . . .
. . . . . . . . . . . . . . . . . . . . 3-40What Are Native
Resources? . . . . . . . . . . . . . . . . . . . . . . . .
3-40Using Garbage Collection Provided by the JVM . . . . . . . . .
3-40Using the dispose Method . . . . . . . . . . . . . . . . . . .
. . . . . . . . 3-41Overriding the Object.Finalize Method . . . . .
. . . . . . . . . . . 3-43Improving Data Access Using the MCR User
DataInterface and MATLAB Builder JA . . . . . . . . . . . . . . .
3-44viiExample: Supplying Run-Time Configuration Informationfor
Parallel Computing Toolbox Applications . . . . . . . . .
3-45Dynamically Specifying Run-Time Options to theMCR . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . 3-49What Run-Time Options Can You Specify? . . . . . . . . . .
. . . 3-49Setting and Retrieving MCR Option Values
UsingMWApplication . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 3-49Handling Data Conversion Between Java
andMATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 3-52Overview . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 3-52Calling MWArray
Methods . . . . . . . . . . . . . . . . . . . . . . . . . .
3-52Creating Buffered Images from a MATLAB Array . . . . . . .
3-53Setting Java Properties . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 3-54How to Set Java System Properties . . . . . . .
. . . . . . . . . . . . 3-54Ensuring a Consistent GUI Appearance .
. . . . . . . . . . . . . . 3-54Blocking Execution of a Console
Application thatCreates Figures . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 3-56waitForFigures Method . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 3-56Code Fragment:
Using waitForFigures to Block Executionof a Console Application . .
. . . . . . . . . . . . . . . . . . . . . . . . 3-57Ensuring
Multi-Platform Portability . . . . . . . . . . . . . . . .
3-59Using MCR Component Cache andMWComponentOptions . . . . . . . .
. . . . . . . . . . . . . . . . . . 3-61MWComponentOptions . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 3-61Selecting
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 3-61Setting Options . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 3-62Learning About Java Classes and
Methods by Exploringthe Javadoc . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 3-64viii ContentsSample Java
Applications4Plot Example . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 4-2Purpose . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-2Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 4-2Spectral Analysis Example . . . . . .
. . . . . . . . . . . . . . . . . . . 4-8Purpose . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-8Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . 4-10Matrix Math Example . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 4-17Purpose . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4-17MATLAB Functions to Be Encapsulated . . . . . . . . . . . . . .
. 4-18Understanding the getfactor Program . . . . . . . . . . . . .
. . . . 4-19Procedure . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 4-19Phonebook Example . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 4-29Purpose . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 4-29Procedure . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 4-29Buffered Image Creation
Example . . . . . . . . . . . . . . . . . . 4-37Purpose . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 4-37Procedure . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . 4-37Optimization Example . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 4-42Purpose . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 4-42OptimDemo Component . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 4-42Procedure . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 4-43Web Application Example
. . . . . . . . . . . . . . . . . . . . . . . . . . 4-53Example
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 4-53Before You Work this Example . . . . . . . . . . . . . .
. . . . . . . . 4-53Downloading the Demo Files . . . . . . . . . .
. . . . . . . . . . . . . . 4-54Build Your Java Component . . . . .
. . . . . . . . . . . . . . . . . . . 4-55Compiling Your Java Code
. . . . . . . . . . . . . . . . . . . . . . . . . . 4-55Generating
the Web Archive (WAR) File . . . . . . . . . . . . . . 4-56Running
the Web Deployment Demo . . . . . . . . . . . . . . . . . .
4-57Using the Web Application . . . . . . . . . . . . . . . . . . .
. . . . . . . 4-57ixDeploying a Java Component Over the Web5About
the WebFigures Feature . . . . . . . . . . . . . . . . . . . . . .
5-2Supported Renderers for WebFigures . . . . . . . . . . . . . . .
. . 5-2Preparing to Implement WebFigures for MATLABBuilder JA . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 5-3Your Role in the WebFigure Deployment Process . . . . . . . .
5-3What You Need to Know to Implement WebFigures . . . . .
5-5Required Products . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 5-5Assumptions About the Examples . . . . . . .
. . . . . . . . . . . . . 5-7Set DISPLAY on UNIX Systems . . . . .
. . . . . . . . . . . . . . . . 5-8Quick Start: Implementing a
Custom WebFigure . . . . . 5-9Overview . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 5-9Setting Up
the Web Server . . . . . . . . . . . . . . . . . . . . . . . . . .
5-9Creating the Default WebFigure . . . . . . . . . . . . . . . . .
. . . . 5-10Interacting with the Default WebFigure . . . . . . . .
. . . . . . . 5-11Creating a Custom WebFigure . . . . . . . . . . .
. . . . . . . . . . . . 5-12Advanced Configuration of a WebFigure .
. . . . . . . . . . . . 5-16Overview . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 5-16How Do
WebFigures Work? . . . . . . . . . . . . . . . . . . . . . . . . .
5-18Installing WebFigureService . . . . . . . . . . . . . . . . . .
. . . . . . 5-19Getting the WebFigure Object from Your Method . . .
. . . . 5-20Attaching a WebFigure . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 5-21Using the WebFigure JSPTag to Reference
a WebFigure . . 5-23Getting an Embeddable String That References
aWebFigure Attached to a Cache . . . . . . . . . . . . . . . . . .
. . 5-26Working with MATLAB Figures and ImagesYour Role in Working
with Figures and Images . . . . . . 6-2Creating and Modifying a
MATLAB Figure . . . . . . . . . . . 6-3Preparing a MATLAB Figure
for Export . . . . . . . . . . . . . . . 6-3x ContentsChanging the
Figure (Optional) . . . . . . . . . . . . . . . . . . . . . .
6-3Exporting the Figure . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 6-4Cleaning Up the Figure Window . . . . . . . .
. . . . . . . . . . . . . 6-4Example: Modifying and Exporting
Figure Data . . . . . . . . 6-4Working with MATLAB Figure and Image
Data . . . . . . 6-6For More Comprehensive Examples . . . . . . . .
. . . . . . . . . . 6-6Working with Figures . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 6-6Working with Images . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 6-6Creating
Scalable Web Applications Using RMI7Using Remote Method Invocation
(RMI) . . . . . . . . . . . . . 7-2Before You Use RMI . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 7-3Running the
Client and Server on a Single Machine . . 7-4Running the Client and
Server on SeparateMachines . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . 7-8Using Native Java with
Cell Arrays and StructArrays . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 7-9Why Use Native
Type Cell Arrays and Struct Arrays? . . . . 7-9Before You Use
Native Type Data Marshalling with Cellsand Structs . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10The
Native Java Cell and Struct Example . . . . . . . . . . . . .
7-10For More RMI Examples . . . . . . . . . . . . . . . . . . . . .
. . . . . . 7-16xiReference Information for JavaBRequirements for
the MATLAB Builder JA Product . . 8-2System Requirements . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 8-2Path
Modifications Required for Accessibility . . . . . . . . . . .
8-2Limitations and Restrictions . . . . . . . . . . . . . . . . . .
. . . . . . 8-3Settings for Environment Variables
(DevelopmentMachine) . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 8-3Data Conversion Rules . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 8-8Java to MATLAB
Conversion . . . . . . . . . . . . . . . . . . . . . . . .
8-8MATLAB to Java Conversion . . . . . . . . . . . . . . . . . . .
. . . . . 8-10Unsupported MATLAB Array Types . . . . . . . . . . .
. . . . . . . 8-11Programming Interfaces Generated by the
MATLABBuilder JA Product . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 8-12APIs Based on MATLAB Function Signatures . .
. . . . . . . . 8-12Standard API . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 8-13mlx API . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-15Code Fragment: Signatures Generated for the myprimesExample . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 8-15MWArray Class Specification . . . . . . . . . . . . . . .
. . . . . . . . 8-17Function Reference9ExamplesAHello World (Quick
Start) . . . . . . . . . . . . . . . . . . . . . . . . . . A-2Magic
Square . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . A-2xii ContentsUsing Load and Save . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . A-2Importing Classes .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-2Instantiating a Java Class . . . . . . . . . . . . . . . . . . .
. . . . . . . A-2Using MWNumericArray . . . . . . . . . . . . . . .
. . . . . . . . . . . . A-2Handling Data . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . A-2Automatic Data
Conversion . . . . . . . . . . . . . . . . . . . . . . . .
A-3Calling MWArray Methods . . . . . . . . . . . . . . . . . . . .
. . . . . . A-3Handling Errors . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . A-4Handling Memory . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . A-4Supplying
Run-Time Configuration Information forParallel Computing Toolbox
Applications . . . . . . . . . A-4Ensuring a Consistent GUI
Appearance . . . . . . . . . . . . . A-4COM Components . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . A-4Using
waitForFigures to Block Execution of a ConsoleApplication . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A-5Sample Applications (Java) . . . . . . . . . . . . . . . . . . .
. . . . . . A-5Working with WebFigures . . . . . . . . . . . . . .
. . . . . . . . . . . . A-5Creating and Modifying a MATLAB Figure .
. . . . . . . . . . A-5Working with Figures . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . A-5xiiiWorking with Images . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . A-6Using
RMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . A-6Indexxiv ContentsJGetting Started* Product
Overview on page 1-2* Before You Use MATLAB Builder JA on page 1-4*
Quick Start: Deploying a Component with the Hello World Example
onpage 1-10* Deploying a Component with the Magic Square Example on
page 1-16* Next Steps on page 1-36J Gelllng SlorledProducl
Overviewln lhis seclion...MATLAB Compiler Extension on page 1-2How
the MATLAB Compiler and MATLAB Builder JA Products WorkTogether on
page 1-2How Does Component Deployment Work? on page 1-3Limitations
of Support on page 1-3MAILA8 Compiler ExlensionMATLAB Builder JA
enables you to create Java classes from yourMATLAB programs. These
Java classes can be integrated into Javaprograms and deployed
royalty-free to desktop computers or Web serversthat do not have
MATLAB installed.When used with MATLAB Compiler, the builder
creates deployablecomponents that make MATLAB based computations,
visualizations, andgraphical user interfaces accessible to end
users of the Java programs.When the Java program is deployed to the
Web, multiple users can access itthrough a Web browser.The builder
encrypts your MATLAB functions and generates a Java wrapperaround
them so that they behave just like any other Java class. Java
classescreated with MATLAB Builder JA are portable and run on all
platformssupported by MATLAB. See the Platform Roadmap for MATLAB
for moreinformation.For information about how MATLAB Compiler
works, see The MATLABCompiler Build Process on page 1-23.How lhe
MAILA8 Compiler ond MAILA8 8uilder JAProducls Work IogelherThe
MATLAB Compiler product can compile MATLAB files, MEX-files,MATLAB
objects, or other MATLAB code. The MATLAB Builder JA
product1-2Producl Cvervlewsupports all the features of MATLAB, and
adds support for Java classes,Java objects (instances of a class),
and methods. Using these productstogether, you can generate the
following:* Standalone applications on UNIX, Windows, and Macintosh
platforms* C and C++ shared libraries (dynamically linked
libraries, or DLLs, onMicrosoft Windows)* Enterprise Java
applications for use on any Java compatible platformHow Does
Componenl Deploymenl Work?There are two kinds of deployment:*
Installing components and setting up support for them on a
developmentmachine so that they can be accessed by a developer who
seeks to use themin writing a Java application.* Deploying support
for the components when they are accessed at run timeon an end-user
machine.To accomplish this kind of deployment, you must make sure
that theinstaller you create for the application takes care of
supporting the Javacomponents on the target machine. In general,
this means the MCR mustbe installed, on the target machine. You
must also install the MATLABBuilder JA component.Nole Java
components created with the MATLAB Builder JA product aredependent
on the version of MATLAB with which they were built.Limilolions ol
5upporlMATLAB Builder JA provides a wide variety of support for
various Javatypes and objects. However, MATLAB (MCOS) objects are
not supported asinputs or outputs for compiled or deployed
functions.1-3J Gelllng Slorled8elore You Use MAILA8 8uilder JAln
lhis seclion...Your Role in the Java Application Deployment Process
on page 1-4What You Need to Know on page 1-6Required Products on
page 1-7Configuring Your Environment on page 1-7Your kole in lhe
Jovo Applicolion Deploymenl ProcessDepending on the size of your
organization, you may play one role, or many,in the process of
successfully deploying a Java application.For example, your job may
be to analyze user requirements and satisfy themby writing a
program in MATLAB code. Or, your role may be to implement
theinfrastructure needed to successfully deploy a Java application
to the Web.In smaller installations, you may find one person
responsible for performingtasks associated with multiple roles.The
table Application Deployment Roles, Tasks, and References on page
1-5describes some of the different roles, or jobs, that MATLAB
Builder JA userstypically perform and which tasks they would most
likely perform whenrunning Deploying a Component with the Magic
Square Example on page1-16.1-4Belore You se MAlLABBullder"
!AApplicolion Deploymenl koles, Iosks, ond kelerenceskole Iosks
kelerencesMATLAB programmer * Understandend-user
businessrequirements andthe mathematicalmodels needed tosupport
them.* Write MATLABcode.* Build an executablecomponent withMATLAB
tools(usually withsupport from a Javaprogrammer).* Package
thecomponent fordistribution to endusers.* Pass the
packagedcomponent to theJava programmerfor rollout andfurther
integrationinto the end-userenvironment.Copying the ExampleFiles on
page 1-18Testing the MATLABFile You Want toDeploy on page
1-18Creating theMagic Square JavaComponent on page1-19Packaging
theMagic Square JavaComponent (Optional)on page 1-21Copy the
Package YouCreated (Optional) onpage 1-23Java programmer * Write
Java codeto execute theJava package builtby the MATLABprogrammer.*
Roll out the packagedcomponent andintegrate it intoGathering
FilesNeeded forDeployment on page1-26Testing the JavaComponent in a
JavaApplication on page1-271-5J Gelllng SlorledApplicolion
Deploymenl koles, Iosks, ond kelerences (Conlinued}kole Iosks
kelerencesthe end-userenvironment.* Use the componentin enterprise
Javaapplications, addingand modifying codeas needed.* Address
dataconversion issuesthat may beencountered,according to the
endusers specifications.* Ensure the final Javaapplication
executesreliably in the endusers environment.Distributing
theComponent to EndUsers on page 1-32Integrating JavaClasses
Generatedby MATLAB into a JavaApplication on page1-33Calling Class
Methodsfrom Java on page 1-34Handle DataConversion as Neededon page
1-34Build and Test onpage 1-35External user Execute the
solutioncreated by MATLABand Java programmers.Run the
deployedapplication (outside thescope of this document).Whol You
Need lo KnowThe following knowledge is assumed when you use the
MATLAB BuilderJA product:* If your job function is MATLAB
programmer, the following is required:- A basic knowledge of
MATLAB, and how to work with cell arrays andstructures* If your job
function is Java programmer, the following is required:- Exposure
to the Java programming language- Object-oriented programming
concepts1-6Belore You se MAlLABBullder" !Akequired ProduclsYou must
install the following products to run the example described in
thischapter:* MATLAB* MATLAB Compiler* MATLAB Builder JAConliguring
Your EnvironmenlConfigure your environment to work with the
examples. Consult your systemadministrator or Java programmer
before performing these taskssome maybe unnecessary. Your
administrator or programmer is often the best resourcefor
verifying, installing, or customizing your Java
environment.Verilying Your Jovo EnvironmenlYou may already be
running a compatible version of Java. To find out ifyou have Java
installed on your computer, and if it is compatible with theMATLAB
Builder JA product:J Open a command prompt.2 Enter the command ]ava
-vers1on. If Java is installed, the result lookslike this:]ava
vers1on "versonnuoer"Java{TM) 2 Pun11ne Env1ronnen1. S1andard
Ed111on{bu1Jd versonnuoer.ouJdnuoerJava Ro1Spo1{TM) CJ1en1 vM{bu1Jd
versonnuoer.ouJdnuoer. n1xed node)3 Enter the command ]avac
-vers1on.Nole Alternately, you may have to enter
JAvAR0ME`b1n`]avac-vers1on if you have the user environment
variable JAvAR0ME defined.For information on locating environment
variables, see Setting Up YourJava Environment on page 1-8.1-7J
Gelllng SlorledIf ]avac is installed, the results should look like
this:]avac versonnuoerIf ]ava and ]avac are installed and the
version numbers are at least 1.5, go toDeploying a Component with
the Magic Square Example on page 1-16. Ifnot, go to Setting Up Your
Java Environment on page 1-8.5elling Up Your Jovo EnvironmenlJ
Download and install the Java Developers Kit (JDK) from
SunMicrosystems, Inc. if you do not yet have it installed.The JDK
is a collection of Java classes, run-time environment,
compiler,debugger, and usually source code, for a version of Java.
The contents ofthe JDK collectively make up a Java development
environment.The JDK includes the Java Runtime Environment (JRE), a
collection ofcompiled classes that makes up the Java virtual
machine, a standaloneexecutor of the Java language, on a specific
platform. Ensure your JavaRuntime Environment and JDK are
compatible with the Sun MicrosystemsJDK Version 1.6.0 before
proceeding to the next step.2 Set the environment variable
JAvAR0ME. This tells Java where to find yourinstalled JDK. from the
MATLAB prompt. You can set JAvAR0ME:* On Windows platforms:o
Right-click the My Computer icon and select Properties.b Click the
Advanced tab.c Click Environment Variables.d In the User Variables
area, click New.e In the New User Variable dialog box, enter
JAvAR0ME for Variablename. Enter the absolute path name where your
JDK is installedfor Variable value. Here is the value of a typical
JAvAR0MEenvironment variable:C:`Progran
F1Jes`Java`J0K1.6.0031-8Belore You se MAlLABBullder" !ANole If
JAvAR0ME already exists, select it and click Edit. Enter thepath
name where your JDK is installed.l Click OK to accept changes.* On
UNIX platforms:g Open a command prompt.h Set JAvAR0ME as
follows:se1 JAvAR0ME=J0|pathnae3 Verify that MATLAB is reading the
correct value of JAvAR0ME.o At the command prompt, type ge1env
JAvAR0ME.b The response from MATLAB should be the path name you set
toJAvAR0ME in Configuring Your Environment on page 1-7. If
not,ensure the JDK that MATLAB is pointing to will be compatible
torun this example (at least Java Version 1.5). Consult your
systemadministrator if you are unsure.1-9J Gelllng SlorledOuick
5lorl: Deploying o Componenl wilh lhe Hello WorldExompleln lhis
seclion...About the Hello World Example on page 1-10Before Running
the Hello World Example on page 1-10The Hello World Example on page
1-10Building the Java Component on page 1-11Deploying Hello World
On a Computer with MATLAB, MATLABCompiler, and MATLAB Builder JA
Installed on page 1-13Deploying Hello World On a Computer with Only
the MATLAB CompilerRuntime (MCR) Installed (MATLAB Not Installed)
on page 1-14Aboul lhe Hello World ExompleThis section gives a very
brief example of MATLAB Builder JA functionality.For a more
extensive starter example, refer to Deploying a Component withthe
Magic Square Example on page 1-16.Nole The examples here use the
Windows depJoy1ooJ GUI, a graphicalfront-end interface to MATLAB
Compiler software. For information abouthow to perform these tasks
using the command-line interface to MATLABCompiler software, see
the ncc reference page. For information about how tostart the
Deployment Tool GUI from the command line, see the
depJoy1ooJreference page.8elore kunning lhe Hello World
ExompleBefore running this example, configure your environment. See
ConfiguringYour Environment on page 1-7 .Ihe Hello World ExompleTo
write a function in MATLAB that displays the text heJJo WorJd as
output,you define the following function and save it as
heJJo.n.1-10Culck Slorl. Deploylng o Componenl wllh lhe Hello Vorld
Exomplefunc11on heJJod1sp{`heJJo. WorJd`)8uilding lhe Jovo
ComponenlYou create a Java application by using the Deployment Tool
GUI to build aJava class that wraps around the sample MATLAB code
discussed in TheHello World Example on page 1-10.To compile or
build heJJo using the Deployment Tool, use the followinginformation
as you work through this example:Project name heJJopr]Class name
heJJocJsPackage name heJJopckFile to compile heJJo.nNole When a
component is built, the package name is the same as theproject
name, by default. To change the package name, click the Actionsicon
and select Settings.J Start MATLAB.2 Type depJoy1ooJ at the command
prompt and press Enter. ThedepJoy1ooJ GUI opens.3 Create a
deployment project using the Deployment Project dialog:o Type the
name of your project in the Name field.b Enter the location of the
project in the Location field. Alternately,navigate to the
location.c Select the target for the deployment project from the
Target drop-downmenu.d Click OK.1-11J Gelllng SlorledCreoling o
Jovo Projecl4 On the Build tab:* If you are building a Java
application, click Add class. Type the nameof the class in the
Class Name field, designated by the letter c:For this class, add
files you want to compile by clicking Add files. Toadd another
class, click Add class.Nole You may optionally add supporting
files. For examples of thesefiles, see the depJoy1ooJ Help. To add
these files, in the Shared Resourcesand Helper Files area:o Click
Add files/directoriesb Click Open to select the file or files.5
When you complete your changes, click the Build button (
).1-12Culck Slorl. Deploylng o Componenl wllh lhe Hello Vorld
ExompleWhol ls o MAILA8 8uilder JA Projecl?To use the MATLAB
Builder JA product, you create a project, which specifiesthe MATLAB
code to be used in the components that you want to create.
Thisproduct supports data conversion between Java types and MATLAB
types.For more about projects and their contents, see Anatomy of a
MATLABBuilder JA Project on page 1-20.Whol ls o MAILA8 8uilder JA
Componenl?A component created by the MATLAB Builder JA product is a
standaloneJava package (.]ar file). The package contains one or
more Java classes thatencapsulate MATLAB code. The classes provide
methods that are callabledirectly from Java code.Deploying Hello
World On o Compuler wilh MAILA8,MAILA8 Compiler, ond MAILA8 8uilder
JA lnslolledRun Hello World by entering the following from a system
command shell.J Before proceeding, ensure you have renamed you
package file to heJJopck.When a component is built, the package
name is the same as the projectname, by default. To change the
package name, click the Actions iconand select Settings.2 Navigate
to the directory containing the JAR file.3 Run the following
command on:* Windows:]ava
-cJasspa1hatJaoroot`1ooJbox`]avabu1Jder`]ar`arch`]avabu1Jder.]arheJJopck.]arheJJopck.heJJocJs*
UNIX: ]ava
-cJasspa1hna1Jabroo111ooJbox1]avabu1Jder1]ar1arch1]avabu1Jder.]ar:heJJopck.]arheJJopck.heJJocJs1-13J
Gelllng Slorledwhere:* atJaoroot is the location of your MATLAB
installation* arch is the operating system and processor type of
the local machinNole The above command should be entered on one
continuous line.Deploying Hello World On o Compuler wilh Only
lheMAILA8 Compiler kunlime (MCk} lnslolled (MAILA8Nol lnslolled}J
Before proceeding, ensure you have renamed you package file to
heJJopck.When a component is built, the package name is the same as
the projectname, by default. To change the package name, click the
Actions iconand select Settings.2 Run Hello World by entering the
following from a system command shell:* Windows:]ava
-cJasspa1h|0||00J`1ooJbox`]avabu1Jder`]ar`arch`]avabu1Jder.]arheJJopck.]arheJJopck.heJJocJs*
UNIX: ]ava
-cJasspa1h|0||00J11ooJbox1]avabu1Jder1]ar1arch1]avabu1Jder.]ar:heJJopck.]arheJJopck.heJJocJswhere:*
|0||00J is the location of your MCR installation* arch is the
operating system and processor type of the local machine1-14Culck
Slorl. Deploylng o Componenl wllh lhe Hello Vorld ExompleNole The
above command should be entered on one continuous line.3 If you are
running UNIX, set your system path appropriately. SeeDirectories
Required for Development and Testing and DirectoriesRequired for
Run-Time Deployment.1-15J Gelllng SlorledDeploying o Componenl wilh
lhe Mogic 5quore Exompleln lhis seclion...About This Example on
page 1-16Magic Square Example: MATLAB Programmer Tasks on page
1-16Magic Square Example: Java Programmer Tasks on page 1-26Aboul
Ihis ExompleIn this section, you will step through an example of
how a simple MATLABfunction can be transformed into a deployable
MATLAB Builder JAcomponent.The Magic Square example shows you how
to create a Java component namednag1csquare which contains the
nag1c class, a .]ar file, and other filesneeded to deploy your
application.The class wraps a MATLAB function, nakesqr, which
computes a magicsquare. A magic square is a matrix containing any
number of rows. Theserows, when added horizontally and vertically,
equate to the same value.MATLAB contains a function, nag1c, that
can create magic squares of anydimension. In this example, you will
work with that function.Nole The examples here use the Windows
depJoy1ooJ GUI, a graphicalfront-end interface to MATLAB Compiler
software. For information abouthow to perform these tasks using the
command-line interface to MATLABCompiler software, see the ncc
reference page.Mogic 5quore Exomple: MAILA8 Progrommer IosksThe
following tasks are usually performed by the MATLAB
programmer.1-16Deploylng o Componenl wllh lhe Moglc Squore
ExompleKey Iosks lor lhe MAILA8 ProgrommerIosk kelerencePrepare to
run the example bycopying the MATLAB example filesinto a work
folder.Copying the Example Files on page1-18Test the MATLAB code to
ensure itis suitable for deployment. Testing the MATLAB File
YouWant to Deploy on page 1-18Create a Java package(encapsulating
your MATLABcode in a Java class) by running theBuild function in
depJoy1ooJ.Creating the Magic Square JavaComponent on page 1-19Run
the Packaging Tool to bundleyour Java component with theadditional
files you selected.Packaging the Magic Square JavaComponent
(Optional) on page 1-21Copy the output from the PackagingTool (the
d1s1r1b folder). Copy the Package You Created(Optional) on page
1-23The Magic Square example shows you how to create a Java
component(nag1csquare), which contains the nag1c class, a .]ar file
(which includes the.c1f archive described in How Does the MATLAB
Builder JA Product UseJAR Files? on page 1-23), and other files
needed to deploy your application.The class encapsulates a MATLAB
function, nakesqr, which computes amagic square.The client Java
application, ge1nag1c.]ava converts the array returned bynakesqr to
a native array and displays it on the screen. When you run
thege1nag1c application from the command line, you can pass the
dimension forthe magic square as a command-line argument.Nole The
examples for the MATLAB Builder JA product are
inatJaoroot`1ooJbox`]avabu1Jder`ExanpJes. In most examples,
Windowssyntax is featured (backslashes, instead of forward
slashes). This exampleassumes the work folder is on drive 0:.1-17J
Gelllng SlorledCopying lhe Exomple FilesPrepare to run the example
by copying needed files into your work area asfollows:J Navigate
toatJaoroot`1ooJbox`]avabu1Jder`ExanpJes`Mag1cSquareExanpJe.atJaoroot
is the MATLAB root folder (where MATLAB is installed). Tofind the
value of this variable on your system, type atJaoroot at acommand
prompt.2 Copy the Mag1cSquareExanpJe folder to a work area, for
example,0:`]avabu1JderexanpJes. Avoid using spaces in your
foldernames, if possible. The example files should now reside
in0:`]avabu1JderexanpJes`Mag1cSquareExanpJe.3 Using a command
prompt, navigate to 0:`]avabu1JderexanpJes`Mag1cSquareExanpJe by
switching to the 0: drive and enteringcd
`]avabu1JderexanpJes`Mag1cSquareExanpJe.Iesling lhe MAILA8 File You
Wonl lo DeployNormally you would first create the MATLAB file you
want to deploy. In thisexample, you will test a precreated MATLAB
file (nakesqr.n) containing thepredefined MATLAB function nag1c.J
Using MATLAB, locate the nakesqr.n file
at0:`]avabu1JderexanpJes`Mag1cSquareExanpJe`Mag1c0enoConp.
Thecontents of the file are as follows:func11on y =
nakesqr{x)MAKES0P Mag1c square of s1ze x. Y = MAKES0P{X) re1urns a
nag1c square of s1ze x. Th1s f1Je 1s used as an exanpJe for 1he
MATLA8 8u1Jder JA produc1. Copyr1gh1 2001-2008 The Ma1hWorks. 1nc.y
= nag1c{x)2 At the command prompt, enter nakesqr{5) and view the
results. Theoutput should appear as follows:1-18Deploylng o
Componenl wllh lhe Moglc Squore Exomple17 24 1 8 1523 5 7 14 164 6
13 20 2210 12 19 21 311 18 25 2 9Creoling lhe Mogic 5quore Jovo
ComponenlYou create the Magic Square Java application by using the
Deployment ToolGUI to build a Java class that wraps around the
sample MATLAB codediscussed in Testing the MATLAB File You Want to
Deploy on page 1-18.Use the following information as you work
through this example using theinstructions in Building the Java
Component on page 1-11:Project Name nag1csquareClass Name nag1cFile
to compile nakesqr.nWhol Hoppens in lhe 8uild Process.Nole The
MATLAB Builder JA product uses the JAvAR0ME variable tolocate the
Java Software Development Kit (SDK) on your system. Thecompiler
uses this variable to set the version of the ]avac.exe commandit
uses during compilation.To create a component, the builder does the
following:J Generates Java code to implement your component. The
files are as follows:1-19J Gelllng SlorledycJass.]ava Contains a
Java class withmethods encapsulating theMATLAB functions
specifiedin the project for that class.ycoponentMCPFac1ory.]ava
Java component with firstcharacter of
ycoponentcapitalzed.ycJassreno1e.]ava Contains a remotableJava
class with methodsencapsulating the MATLABfunctions specified in
theproject for that class.See Chapter 7, CreatingScalable Web
ApplicationsUsing RMI.package-1nfo.]ava Javadoc
packagedocumentation.2 Compiles the Java code produced in step 1.3
Generates /d1s1r1b and /src subfolders.4 Invokes the Jar utility to
package the Java class files it has created into aJava archive file
(ycoponent.]ar).For information about how MATLAB Compiler works,
see The MATLABCompiler Build Process on page 1-23.Anolomy ol o
MAILA8 8uilder JA Projecl. A builder project containsinformation
about the files and settings needed by the MATLAB Builder JAproduct
to create a deployable Java component. A project specifies
informationabout classes and methods, including the MATLAB
functions to be included.Classes and MethodsThe builder transforms
MATLAB functions that are specified in thecomponents project to
methods belonging to a Java class.1-20Deploylng o Componenl wllh
lhe Moglc Squore ExompleWhen creating a component, you must provide
one or more class names aswell as a component name. The class name
denotes the name of the classthat 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 methodsthat encapsulate the MATLAB functions.Nole
When you add files to a project, you do not have to add any
MATLABfiles for functions that are called by the functions that you
add. When theMATLAB Builder JA product builds a component, it
automatically includesany MATLAB functions called by the functions
that you explicitly specify forthe component. See Spectral Analysis
Example on page 4-8 for a sampleapplication that illustrates this
feature.Naming ConventionsTypically you should specify names for
components and classes that will beclear to programmers who use
your components. For example, if you areencapsulating many MATLAB
functions, it helps to determine a scheme offunction categories and
to create a separate class for each category. Also, thename of each
class should be descriptive of what the class does.Valid characters
are any alpha or numeric characters, as well as theunderscore ()
character.Pockoging lhe Mogic 5quore Jovo Componenl
(Oplionol}Bundling the Java component with additional files into a
JAR file that canbe distributed to users is called packaging. You
will perform this step usingthe packaging function of depJoy1ooJ.
Alternately, copy the contents of thed1s1r1b folder and the MCR
Installer to a local folder of your choice. If youare creating a
shared component and want to include additional code with
thecomponent, you must perform this step.1-21J Gelllng SlorledNole
Packaging a component and a Java package are different
concepts.Packaging in this context refers only to the act of using
MATLAB BuilderJA to bundle the Java component with associated files
needed to successfullydeploy the application. A Java package is a
collection of Java classes andmethods.J On the Package tab, add the
MATLAB Compiler Runtime (the MCR) byclicking Add MCR.2 Next, add
others files useful for end users. The readne.1x1 file
containsimportant information about others files useful for end
users. To packageadditional files or folders, click Add
file/directories, select the file orfolder you want to package, and
click Open.3 In the Deployment Tool, click the Packaging button (
).4 On Windows, the package is a self-extracting executable. On
platformsother than Windows, it is a .z1p file. Verify that the
contents of thed1s1r1b folder contains the files you specified.Nole
When the self-extracting executable is uncompressed on a
system,vCPE0S1TX86 is installed. vCPE0S1TX86 installs run-time
componentsof Microsoft Visual C++ libraries necessary for running
Visual C++applications.Whol Hoppens in lhe Pockoging Process?. The
packaging processcreates a self-extracting executable (on Windows
platforms) or a .z1p file (onplatforms other than Windows). The
package contains at least the following:* The builder component*
The MCR Installer (if the Install MCR option was selected when
thecomponent was built)* Documentation generated by the Sun
Microsystems Javadoc tool1-22Deploylng o Componenl wllh lhe Moglc
Squore ExompleNole The packaging process is not available when
using ncc directly.Nole For guidelines on multi-platform
portability, reference EnsuringMulti-Platform Portability on page
3-59.How Does lhe MAILA8 8uilder JA Producl Use JAk Files?. As
ofR2007b, the MATLAB Builder JA product now embeds the CTF
archivewithin the generated JAR file, by default. This offers
convenient deploymentof a single output file since all encrypted
MATLAB file data is now containedwithin this Java archive.For
information on CTF archive data extraction and utilizationusing
MWConponen10p11ons see Using MCR Component Cache
andMWComponentOptions on page 3-61.Copy lhe Pockoge You Creoled
(Oplionol}Copy the package that you created from the d1s1r1b folder
to the local folderof your choice or send them directly to the Java
programmer..Ihe MAILA8 Compiler 8uild ProcessTo generate and
package an application, the user:J Writes an application or
component in MATLAB2 Invokes the MATLAB Compiler, which:o Examines
the input MATLAB files and the external dependencydatabase to
determine the complete list of all functions used by theapplication
or component. As part of this process, MATLAB Compilerdetermines
which files are not able to be compiled and automaticallyexcludes
them.b Determines which functions are to be made publicly visible
(for example,those that can be called from another product or
environment).1-23J Gelllng Slorledc Generates the appropriate
interface code files based on the publicfunction list and the
complete function list from the preceding steps. Theinterface code
generated is also dependent on what target the user wantsto create
(for example, a Java component, a standalone executable, or
aMicrosoft Excel add-in).d Packages compilable functions into a CTF
archive, creating a file on theusers disk. This archive is embedded
by default in the binary executable.e Optionally, invokes target
specific compiler to generate a binaryapplication or component from
the files in C and the interface codelibraries provided by The
MathWorks.3 Locates the install package for the MATLAB Compiler
Runtime (MCR).4 Collects together the binary, the CTF archive, and
the MCR installer (alongwith other optional, user-specified files)
for the user.The deployment GUI (depJoy1ooJ) automates many of the
steps in theprocess for user convenience.1-24Deploylng o Componenl
wllh lhe Moglc Squore Exomple1-25J Gelllng SlorledMogic 5quore
Exomple: Jovo Progrommer IosksThe following tasks are usually
performed by the Java programmer.Key Iosks lor lhe Jovo
ProgrommerIosk kelerenceEnsure you have the needed filesfrom the
MATLAB Programmerbefore proceeding.Gathering Files Needed
forDeployment on page 1-26Test the Java code by using it in aJava
application. Compile and runthe component to ensure it producesthe
same results as your MATLABcode.Creating the Magic Square
JavaComponent on page 1-19Archive and distribute the output toend
users. Distributing the Component to EndUsers on page 1-32Import
classes generated by theMATLAB Builder JA product intoexisting Java
applications.Integrating Java Classes Generatedby MATLAB into a
Java Applicationon page 1-33Use built-in Java class methods
toenhance your Java application. Calling Class Methods from Javaon
page 1-34Address potential data conversionissues with differing
data types. Handle Data Conversion as Neededon page 1-34Verify your
Java application worksas expected in your end usersdeployment
environment.Build and Test on page 1-35Golhering Files Needed lor
DeploymenlBefore beginning, verify you have access to the following
files, created by theMATLAB Programmer in Copy the Package You
Created (Optional) on page1-23. The following files are required to
deploy to users who do not have acopy of MATLAB installed:* MCR
Installer. For locations of the MCR Installer, run the
ncr1ns1aJJercommand.1-26Deploylng o Componenl wllh lhe Moglc Squore
Exomple* Javadoc documentation* readne.1x1 fileSee Packaging the
Magic Square Java Component (Optional) on page1-21 for more
information about these files. You will also want tocommunicate the
location of
con.na1hWorks.1ooJbox.]avabu1Jder(atJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar).
You canbrowse the API Javadoc for con.na1hWorks.1ooJbox.]avabu1Jder
from theMATLAB Help.Iesling lhe Jovo Componenl in o Jovo
ApplicolionBefore deploying the created component, you need to
verify that it can be usedin a Java application successfully.First,
create a small Java program that uses the component created foryour
by the MATLAB Programmer (see Packaging the Magic Square
JavaComponent (Optional) on page 1-21). The example provides a
sampleJava program that accomplishes this (ge1nag1c.]ava now in the
folder0:`]avabu1JderexanpJes`Mag1cSquareExanpJe`Mag1c0enoJavaApp).The
program imports the nag1csquare package you createdwith depJoy1ooJ
and the MATLAB Builder JA
package(con.na1hWorks.1ooJbox.]avabu1Jder) and uses one of
theMATLAB Builder JA conversion classes to convert the number
passed to theprogram on the command line into a type that can be
accepted by MATLAB,in this case a scalar double value.The program
then creates an instance of class nag1c, and calls the
nakesqrmethod on that object. Note how the MATLAB file becomes a
method ofthe Java class that encapsulates it. As explained in
Testing the MATLABFile You Want to Deploy on page 1-18, the nakesqr
method computes thesquare using the MATLAB nag1c function. The
source code of ge1nag1c.]avafollows, for your reference:1*
ge1nag1c.]ava* Th1s f1Je 1s used as an exanpJe for 1he MATLA8*
8u1Jder JA produc1.** Copyr1gh1 2008 The Ma1hWorks. 1nc.1-27J
Gelllng Slorled*11* Necessary package 1npor1s *11npor1
con.na1hWorks.1ooJbox.]avabu1Jder.*1npor1 nag1csquare.*1** ge1nag1c
cJass conpu1es a nag1c square of order N. The* pos111ve 1n1eger N
1s passed on 1he connand J1ne.*1cJass ge1nag1c{pubJ1c s1a11c vo1d
na1n{S1r1ng|] args){MWNuner1cArray n = nuJJ 1* S1ores 1npu1 vaJue
*10b]ec1|] resuJ1 = nuJJ 1* S1ores 1he resuJ1 *1nag1c 1heMag1c =
nuJJ 1* S1ores nag1c *11* cJass 1ns1ance *11ry{1* 1f no 1npu1. ex11
*11f {args.Jeng1h == 0){Sys1en.ou1.pr1n1Jn{"Error: nus1 1npu1 a
pos111ve1n1eger")re1urn}1* Conver1 and pr1n1 1npu1 vaJue*1n = neW
MWNuner1cArray{0oubJe.vaJue0f{args|0]).MWCJass10.00u8LE)Sys1en.ou1.pr1n1Jn{"Mag1c
square of order " +n.1oS1r1ng{))1* Crea1e neW nag1c ob]ec1
*11heMag1c = neW nag1c{)1* Conpu1e nag1c square and pr1n1 resuJ1
*11-28Deploylng o Componenl wllh lhe Moglc Squore ExompleresuJ1 =
1heMag1c.nakesqr{1. n)Sys1en.ou1.pr1n1Jn{resuJ1|0])}ca1ch
{Excep11on e){Sys1en.ou1.pr1n1Jn{"Excep11on: " +
e.1oS1r1ng{))}f1naJJy{1* Free na11ve resources
*1MWArray.d1sposeArray{n)MWArray.d1sposeArray{resuJ1)1f {1heMag1c
!= nuJJ)1heMag1c.d1spose{)}}}Ensure your current working folder is
set to0:`]avabu1JderexanpJes`Mag1cSquareExanpJe as noted previously
in thisexample. Then, do the following:J Compile the Java component
with the Java compiler, ]avac. At thecommand prompt, enter one of
the following commands. When enteringthese commands, ensure they
are entered as one continuous command. OnWindows systems, the
semicolon () is a concatenation character. On UNIXsystems, the
colon (:) is a concatenation character.* On Windows
platforms:JAvAR0ME`b1n`]avac
-cJasspa1hatJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar.`nag1csquare`d1s1r1b`nag1csquare.]ar.`Mag1c0enoJavaApp`ge1nag1c.]ava*
On UNIX platforms:$JAvAR0ME1b1n1]avac
-cJasspa1h.:atJaoroot11ooJbox1]avabu1Jder1-29J Gelllng
Slorled1]ar1]avabu1Jder.]ar:.1nag1csquare1d1s1r1b1nag1csquare.]ar.1Mag1c0enoJavaApp1ge1nag1c.]avaInspect
the syntax of the ]avac compile command on Windows
platforms:JAvAR0ME`b1n`]avac
-cJasspa1hatJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar.`nag1csquare`d1s1r1b`nag1csquare.]ar.`Mag1c0enoJavaApp`ge1nag1c.]avaThe
components of this command are:* JAvAR0ME1b1n1]avac Using this
command invokes the Javacompiler explicitly from the version of
Java you set with JAvAR0ME (seeConfiguring Your Environment on page
1-7).Nole JAvAR0ME is Windows syntax and $JAvAR0ME is UNIX syntax.*
-cJasspa1h Using this argument allows Java to access the packages
andother files you need to compile your component.*
atJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar The location of
the MATLAB Builder JA package
file(con.na1hWorks.1ooJbox.]avabu1Jder).*
.`nag1csquare`d1s1r1b`nag1csquare.]ar The location of
thenag1csquare package file you created with depJoy1ooJ.*
.`Mag1c0enoJavaApp`ge1nag1c.]ava The location of thege1nag1c.]ava
source file.2 When you run ge1nag1c, you pass an input argument to
Java representingthe dimension for the magic square. In this
example, the value for thedimension is 5. Run ge1nag1c by entering
one of the following ]avacommands at the command prompt. When
entering these commands,ensure they are entered as one continuous
command. On Windows systems,the semicolon () is a concatenation
character. On UNIX systems, the colon(:) is a concatenation
character.1-30Deploylng o Componenl wllh lhe Moglc Squore Exomple*
On Windows
platforms:JAvAR0ME`b1n`]ava-cJasspa1h.`Mag1c0enoJavaAppatJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar.`nag1csquare`d1s1r1b`nag1csquare.]arge1nag1c
5* On UNIX
platforms:$JAvAR0ME1b1n1]ava-cJasspa1h.1Mag1c0enoJavaApp:atJaoroot11ooJbox1]avabu1Jder1]ar1]avabu1Jder.]ar:.1nag1csquare1d1s1r1b1nag1csquare.]arge1nag1c
5Inspect the syntax of the ]ava command on Windows
platforms:JAvAR0ME`b1n`]ava-cJasspa1h.`Mag1c0enoJavaAppatJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar.`nag1csquare`d1s1r1b`nag1csquare.]arge1nag1c
5Nole If you are running on the Mac 64-bit platform, you must add
the-d64 flag in the Java command. See Limitations and Restrictions
on page8-3 for more specific information.The components of this
command are:* JAvAR0ME`b1n`]ava Using this command invokes the ]ava
runtime explicitly from the MATLAB JRE.* -cJasspa1h Using this
argument allows Java to access the packagesand other files you need
to run your application.* .`Mag1c0enoJavaApp The location of
ge1nag1c.cJass. Thesemicolon concatenates this file location with
the following file location,so Java can find the files needed to
run your program.1-31J Gelllng Slorled*
atJaoroot`1ooJbox`]avabu1Jder`]ar`]avabu1Jder.]ar The location of
the MATLAB Builder JA package
file(con.na1hWorks.1ooJbox.]avabu1Jder). The semicolon
concatenatesthis file location with the following file location, so
Java can find thefiles needed to run your program.*
.`nag1csquare`d1s1r1b`nag1csquare.]ar The location of
thenag1csquare package file you created with depJoy1ooJ.* ge1nag1c
5 Invokes the compiled ge1nag1c application with thecommand-line
argument 5.3 Verify the program output. If the program ran
successfully, a magic squareof order 5 will print, matching the
output of the MATLAB function you ranin Testing the MATLAB File You
Want to Deploy on page 1-18, as follows:Mag1c square of order 517
24 1 8 1523 5 7 14 164 6 13 20 2210 12 19 21 311 18 25 2 9Using
mcrrool lo Iesl Agoinsl lhe MCk. To test directly against the
MCR,substitute crroot for atJaoroot, where crroot is the location
where theMCR is installed on your system. An example of an MCR root
location
is0:`AppJ1ca11ons`MATLA8`MATLA8Conp1JerPun11ne`|0|versonnuoer.Remember
to double-quote all parts of the ]ava command path argumentsthat
contain spaces.Dislribuling lhe Componenl lo End UsersIf you
bundled the component as a self-extracting executable, paste it in
afolder on the development machine, and run it. If you are using a
.z1p filebundled with WinZip, unzip and extract the contents to the
developmentmachine.1-32Deploylng o Componenl wllh lhe Moglc Squore
Exomplelnlegroling Jovo Closses Generoled by MAILA8 inlo o
JovoApplicolionIf you are implementing your Java component on a
computer other than theone on which it was built:J Install the
MATLAB Compiler Runtime on the target system. SeeDeployment Process
in the MATLAB Compiler documentation.2 Consult the Javadoc for
information on classes generated by MATLABclasses. Reference the
Javadoc from the MATLAB Builder JA productroadmap.3 To integrate
the Java class generated by MATLAB Builder JA,softwareboth the
component and the MWArray API need to be imported in the Javacode.
Import the MATLAB libraries and the component classes into yourcode
with the Java 1npor1 function. For example:1npor1
con.na1hWorks.1ooJbox.]avabu1Jder.*1npor1 coponentnae.cJassnae or
1npor1 coponentnae.*For more information, see Chapter 3,
Programming.4 As with all Java classes, you must use the neW
function to create aninstance of a class. To create an object
(1heMag1c) from the nag1c class,the example application uses the
following code:1heMag1c = neW nag1c{)For more information, see
Chapter 3, Programming.5 To conserve system resources and optimize
performance, it is good practiceto get in the habit of destroying
any instances of classes that are no longerneeded. For example, to
dispose of the object 1heMag1c, use the
followingcode:1heMag1c.d1spose{)1* Make 11 eJ1g1bJe for garbage
coJJec11on *11heMag1c = nuJJFor more information, see Chapter 3,
Programming, in particular, Usingthe dispose Method on page
3-41.1-33J Gelllng SlorledColling Closs Melhods lrom JovoAfter you
have instantiated the class, you can call a class method as
youwould with any Java object. In the Magic Square example, the
nakesqrmethod is called as shown:resuJ1 = 1heMag1c.nakesqr{1.
n)Here n is an instance of an MWArray class. Note that the first
argumentexpresses number of outputs (1) and succeeding arguments
represent inputs(n).See the following code fragment for the
declaration of n:n = neW
MWNuner1cArray{0oubJe.vaJue0f{args|0].MWCJass10.00u8LE)Nole The
MATLAB Builder JA product provides a rich API for integratingthe
generated components. Detailed examples and complete listings of
inputparameters and possible thrown exceptions can be found in the
Javadoc,available from thethe MATLAB Builder JA roadmap.Hondle Dolo
Conversion os NeededWhen you invoke a method on a builder
component, the input parametersreceived by the method must be in
the MATLAB internal array format. Youcan either (manually) convert
them yourself within the calling program, orpass the parameters as
Java data types.* To manually convert to one of the standard MATLAB
data types, useMWArray classes in the package
con.na1hWorks.1ooJbox.]avabu1Jder.* If you pass them as Java data
types, they are automatically converted.How MAILA8 8uilder JA
Hondles Dolo. To enable Javaapplications to exchange data with
MATLAB methods theyinvoke, the builder provides an API, which is
implemented as thecon.na1hWorks.1ooJbox.]avabu1Jder.MWArray
package. This packageprovides a set of data conversion classes
derived from the abstract class,MWArray. Each class represents a
MATLAB data type.1-34Deploylng o Componenl wllh lhe Moglc Squore
ExompleFor more detailed information on data handling within
theproduct and programming with the MWArray package, see
thecon.na1hWorks.1ooJbox.]avabu1Jder.MWArray Javadoc and About
theMATLAB Builder JA API on page 3-3.8uild ond IeslBuild and test
the Java application as you would any application in your endusers
environment. Build on what youve created by working with
additionalclasses and methods.After you create and distribute the
initial application, you will want tocontinue to enhance it.
Details about some of the more common tasks you willperform as you
develop your application are listed in the chapters described
inNext Steps on page 1-36.kunning o 64-8il Moc ApplicolionBefore
you run a 64-bit Macintosh application, you need to use the
theMacintosh Application Launcher. See Running Your 64-Bit Mac
Applicationin the MATLAB Compiler User Guide for more
information.See Using MATLAB Compiler on UNIX in the MATLAB
Compiler UserGuide for complete information about building,
deploying, and testing UNIXapplications with MATLAB Compiler.1-35J
Gelllng SlorledNexl 5lepsWriting Java applications thatcan access
Java methods thatencapsulate MATLAB codeChapter 3,
ProgrammingSample applications that accessmethods developed in
MATLAB Chapter 4, Sample JavaApplicationsDeploying Java components
over theWeb Chapter 5, Deploying a JavaComponent Over the
WebReference information aboutautomatic data conversion rules
Chapter 8, Reference Informationfor Java1-362Writing
DeployableMATLAB Code* The MATLAB Application Deployment Products
on page 2-2* Building Your Application with the Application
Deployment Products andthe Deployment Tool on page 2-4* Guidelines
for Writing Deployable MATLAB Code on page 2-10* Working with
MATLAB Data Files Using Load and Save on page 2-142 Vrlllng
Deployoble MAlLABCodeIhe MAILA8 Applicolion Deploymenl
ProduclsM/T|/B erue|tlc lT erue|iercelc occess tc lT s]steas0eelcus
acJeluses t|e |uilJe| tccls tc c|eote occaucrert t|ot is cier tc
t|e|usiress se|ice Jeelcue|The following tables summarizes the
target applications supported by eachproduct.:Ihe MAILA8 5uile ol
Applicolion Deploymenl ProduclsProducl Iorgel
Creole5londoloneExeculobles?CreoleFunclionLibrories?CreoleApplicolionswilhGrophics?Creole
WebApplicolions?MATLABCompiler C and C++standalonesand librariesYes
Yes Yes NoMATLABBuilder NE C# .NETcomponentsVisualBasic
COMcomponentsNo Yes Yes YesMATLABBuilder JA Javacomponents No Yes
Yes YesMATLABBuilder EX MicrosoftExcel add-ins No Yes Yes No2-2lhe
MAlLABAppllcollon Deploymenl ProduclsIhe MAILA8Applicolion
Deploymenl ProduclsEach of the builder products uses the MATLAB
Compiler core code to createdeployable components.2-32 Vrlllng
Deployoble MAlLABCode8uilding Your Applicolion wilh lhe Applicolion
DeploymenlProducls ond lhe Deploymenl Ioolln lhis seclion...What Is
the Difference Between the Deployment Tool and the mccCommand Line?
on page 2-4How Does MATLAB Compiler Software Build My Application?
on page2-4What You Should Know About the Dependency Analysis
Function(depfun) on page 2-5Compiling MEX-Files, DLLs, or Shared
Libraries on page 2-6The Role of the Component Technology File (CTF
Archive) on page 2-7Whol ls lhe Dillerence 8elween lhe Deploymenl
Ioolond lhe mcc Commond Line?Using the Deployment Tool (depJoy1ooJ)
GUI, you perform any function youwould invoke using the MATLAB
Compiler ncc command-line interface. TheDeployment Tool interactive
menus and dialogs build ncc commands that arecustomized to your
specification. As such, your MATLAB code is processedthe same way
as if you were compiling it using ncc.Using the Deployment Tool,
you:* Perform related deployment tasks with a single intuitive
GUI.* Maintain related information in a convenient project file.
Your projectstate persists between sessions. Your previous project
loads automaticallywhen the Deployment Tool starts. You load
previously stored compilerprojects from a prepopulated menu.*
Package applications for distribution.How Does MAILA8 Compiler
5ollwore 8uild MyApplicolion?MATLAB Compiler software:2-4Bulldlng
Your Appllcollon wllh lhe Appllcollon Deploymenl Producls ond lhe
Deploymenl loolJ Parses command-line arguments and classifies by
type the files you provide.2 Analyzes files for dependencies using
the Dependency Analysis Function(depfun). Dependencies affect
deployability and originate from filecontentsfunctions called by
the file. Deployability is affected by:* File type MATLAB, Java,
MEX, and so on.* File location MATLAB, MATLAB toolbox, user code,
and so on.* File deployability Whether the file is deployable
outside of MATLABFor more information about depfun, see What You
Should Know Aboutthe Dependency Analysis Function (depfun) on page
2-5.3 Validates MEX-files. In particular, nexFunc11on entry points
are verified).For more details about MEX-file processing, see
Compiling MEX-Files,DLLs, or Shared Libraries on page 2-6.4 Creates
a CTF archive from the input files and their dependencies.For more
details about CTF archives see The Role of the ComponentTechnology
File (CTF Archive) on page 2-7.5 Generates target-specific wrapper
code. For example, the wrapper for a Cmain function is very
different than the wrapper for a Java interface class.6 Invokes a
third-party target-specific compiler to create the
appropriatebinary software component (a standalone executable, a
Java JAR file,and so on).For details about how MATLAB Compiler
software builds your deployablecomponent, see The MATLAB Compiler
Build Process on page 1-23.Whol You 5hould Know Aboul lhe
DependencyAnolysis Funclion (deplun}MATLAB Compiler uses a
dependency analysis function (depfun) todetermine the list of
necessary files to include in the CTF package. In somecases, this
process includes an large number of files. This is often true
whenMATLAB object classes exist in the compilation and depfun
cannot resolveoverloaded methods at compile time. Dependency
analysis also processes1ncJude/excJude files on each pass (see the
ncc flag -a Add to Archive).2-52 Vrlllng Deployoble MAlLABCodeIip
To improve compile time performance and lessen application size,
prunethe path with -N Clear Path, -p Add Directory to Path, or by
specifyingToolboxes on Path in the depJoy1ooJ Settingsdepfun
searches for executable content such as:* MATLAB files* P-files*
Java classes and .]ar files* .f1g files* MEX-filesdepfun does not
search for data files of any kind (except MAT files). Youmust
manually 1ncJude data files.Compiling MEX-Files, DLLs, or 5hored
LibroriesWhen you compile MATLAB functions containing MEX-files,
ensurethat depfun can find themdoing so allows you to avoid many
commoncompilation problems. In particular, note that:* depfun
cannot examine MEX-files, DLLs, or shared libraries to
determinetheir dependencies. Explicitly include all binaries these
files requireeither with the ncc -a option or the options on the
Advanced tab in theDeployment Tool under Settings.* If you have any
doubts that depfun can find a MATLAB function called bya MEX-file,
DLL, or shared librarymanually include it. Do this witheither the
ncc -a option or by using the options on the Advanced tab inthe
Deployment Tool under Settings.* Not all functions are compatible
with MATLAB Compiler. Check the filenccExcJudedF1Jes.Jog after your
build completes. This file lists allfunctions called from your
application that you cannot deploy.2-6Bulldlng Your Appllcollon
wllh lhe Appllcollon Deploymenl Producls ond lhe Deploymenl loolIhe
kole ol lhe Componenl Iechnology File (CIFArchive}Each application
or shared library produced by MATLAB Compiler has anassociated
Component Technology File (CTF) archive. The archive containsall
the MATLAB based content (MATLAB files, MEX-files, and so
on)associated with the component.MATLAB Compiler also embeds a CTF)
archive in each generated binary.The CTF houses all deployable
files. All MATLAB files encrypt in the CTFarchive using the
Advanced Encryption Standard (AES) cryptosystem.If you choose the
extract the CTF archive as a separate file the files
remainencrypted. For more information on how to extract the CTF
archive refer tothe references in the following table.lnlormolion
on CIF Archive EmbeddingJExlroclion ond ComponenlCocheProducl keler
loMATLAB Compiler Overriding Default CTF ArchiveEmbedding Using the
MCRComponent CacheMATLAB Builder NE Overriding Default CTF
ArchiveEmbedding for Components Usingthe MCR Component CacheMATLAB
Builder JA Using MCR Component Cache andMWComponentOptions on
page3-61MATLAB Builder EX Overriding Default CTF ArchiveEmbedding
for Components Usingthe MCR Component Cache2-72 Vrlllng Deployoble
MAlLABCode2-8Bulldlng Your Appllcollon wllh lhe Appllcollon
Deploymenl Producls ond lhe Deploymenl loolAddilionol
DeloilsMultiple CTF archives, such as those generated with COM,
.NET, or Excelcomponents, can coexist in the same user application.
You cannot, however,mix and match the MATLAB files they contain.
You cannot combineencrypted and compressed MATLAB files from
multiple CTF archives intoanother CTF archive and distribute
them.All the MATLAB files from a given CTF archive associate with a
uniquecryptographic key. MATLAB files with different keys, placed
in the sameCTF archive, do not execute. If you want to generate
another applicationwith a different mix of MATLAB files, recompile
these MATLAB files into anew CTF archive.MATLAB Compiler deleted
the CTF archive and generated binary followinga failed compilation,
but only if these files did not exist before compilationinitiates.
Run heJp ncc -K for more information.Coulion Release Engineers and
Software Configuration Managers:Do not use build procedures or
processes that strip shared libraries on CTFarchives. If you do,
you can possibly strip the CTF archive from the binary,resulting in
run-time errors for the driver application.2-92 Vrlllng Deployoble
MAlLABCodeGuidelines lor Wriling Deployoble MAILA8 Codeln lhis
seclion...Compiled Applications Do Not Process MATLAB Files at
Runtime onpage 2-10Do Not Rely on Changing Directory or Path to
Control the Execution ofMATLAB Files on page 2-11Use ismcc and
isdeployed Functions To Execute Deployment-Specific CodePaths on
page 2-11Gradually Refactor Applications That Depend on
NoncompilableFunctions on page 2-12Do Not Create or Use Nonconstant
Static State Variables on page 2-12Compiled Applicolions Do Nol
Process MAILA8 Filesol kunlimeThe MATLAB Compiler was designed so
that you can deploy locked downfunctionality. Deployable MATLAB
files are suspended or frozen at thetime MATLAB Compiler encrypts
themthey do not change from that pointonward. This does not mean
that you cannot deploy a flexible applicationitmeans that you must
design your application with flexibility in mind. If youwant the
end user to be able to choose between two different methods,
forexample, they both must be compiled in.The MCR only works on
MATLAB code that was encrypted when thecomponent was built. Any
function or process that dynamically generatesnew MATLAB code will
not work against the MCR.Some MATLAB toolboxes, such as the Neural
Network Toolbox product,generate MATLAB code dynamically. Because
the MCR only executesencrypted MATLAB files, and the Neural Network
Toolbox generatesunencrypted MATLAB files, some functions in the
Neural Network Toolboxcannot be deployed.Similarly, functions that
need to examine the contents of a MATLAB functionfile cannot be
deployed. RELP, for example, is dynamic and not available
in2-10Guldellnes lor Vrlllng Deployoble MAlLABCodedeployed mode.
You can use LOADLIBRARY in deployed mode if you provideit with a
MATLAB function prototype.Instead of compiling the function that
generates the MATLAB code andattempting to deploy it, perform the
following tasks:J Run the code once in MATLAB to obtain your
generated function.2 Compile the MATLAB code with MATLAB Compiler,
including thegenerated function.Iip Another alternative to using
EvAL or FEvAL is using anonymous functionhandles.If you require the
ability to create MATLAB code for dynamic runtimeprocessing, your
end-users must have an installed copy of MATLAB.Do Nol kely on
Chonging Direclory or Polh lo Conlrollhe Execulion ol MAILA8
FilesIn general, good programming practices advise against
redirecting a programsearch path dynamically within the code. Many
programmers are proneto this behavior since it mimics the actions
they usually perform on thecommand line. However, this can lead to
problems when deploying code.For example, in a deployed
application, the MATLAB and Java paths arefixed and cannot change.
Therefore, any attempts to change these paths(using the cd command
or the addpa1h command) failsIf you find you cannot avoid placing
addpa1h calls in your MATLAB code, use1sncc and 1sdepJoyed. See the
next section for details.Use ismcc ond isdeployed Funclions Io
ExeculeDeploymenl-5pecilic Code PolhsThe 1sdepJoyed function allows
you to specify which portion of your MATLABcode is deployable, and
which is not. Such specification minimizes yourcompilation errors
and helps create more efficient, maintainable code.2-112 Vrlllng
Deployoble MAlLABCodeFor example, you find it unavoidable to use
addpa1h when writing yours1ar1up.n. Using 1sncc and 1sdepJoyed, you
specify when and what iscompiled and executed.For an example of
using 1sdepJoyed, see Passing Arguments to and froma Standalone
Application.Groduolly keloclor Applicolions Ihol Depend
onNoncompiloble FunclionsOver time, refactor, streamline, and
modularize MATLAB code containingnon-compilable or non-deployable
functions that use 1sncc and 1sdepJoyed.Your eventual goal is
graceful degradation of non-deployable code. Inother words, the
code must present the end user with as few obstacles todeployment
as possible until it is practically eliminated.Partition your code
into design-time and run-time code sections:* Design-time code is
code that is currently evolving. Almost all code goesthrough a
phase of perpetual rewriting, debugging, and optimization. Insome
toolboxes, such as the Neural Network Toolbox product, the code
goesthrough a period of self-training as it reacts to various data
permutationsand patterns. Such code is almost never designed to be
deployed.* Run-time code, on the other hand, has solidified or
become stableit is in afinished state and is ready to be deployed
by the end user.Consider creating a separate directory for code
that is not meant to bedeployed or for code that calls undeployable
code.Do Nol Creole or Use Nonconslonl 5lolic 5loleVorioblesAvoid
using the following:* Global variables in MATLAB code* Static
variables in MEX-files* Static variables in Java code2-12Guldellnes
lor Vrlllng Deployoble MAlLABCodeThe state of these variables is
persistent and shared with everything in theprocess.Persistent
variables can cause problems because the MCR process runs in
asingle thread. You cannot load more than one of these
non-constant, staticvariables into the same process. In addition,
these static variables do notwork well in multithreaded
applications.If you must use static variables, bind them to
instances. For example,defining instance variables in a Java class
is preferable to defining thevariable as s1a11c.Nole This guideline
does not apply to MATLAB Builder EX customers.When programming with
Microsoft Excel, you can assign global variables tolarge matrices
that persist between calls.2-132 Vrlllng Deployoble
MAlLABCodeWorking wilh MAILA8 Dolo Files Using Lood ond 5oveIf your
deployed application uses MATLAB data files (MAT-files), it is
helpfulto code L0A0 and SAvE functions to manipulate the data and
store it for laterprocessing.* Use 1sdepJoyed to determine if your
code is running in or out of theMATLAB workspace.* Specify the data
file by full path name or relative to c1froo1.* All MAT-files are
unchanged after ncc runs. These files are not encryptedwhen written
to the CTF archive.For more information about CTF archives, see The
Role of the ComponentTechnology File (CTF Archive) on page 2-7.Use
the following example as a template for manipulating your
MATLABdata inside, and outside, of MATLAB.Using LoodJ5ove Funclions
lo Process MAILA8 Dololor Deployed ApplicolionsThe following
example specifies three MATLAB data files:* userda1a.na1*
userda1a1ex1rada1a.na1* ..1ex1ernda1a1ex1ernda1a.na1Compile
exJoadsave.n with the following ncc command:ncc -nvC exJoadsave.n
-a `userda1a.na1` -a`.1userda1a1ex1rada1a.na1`
-a`..1ex1ernda1a1ex1ernda1a.na1`ex_loodsove.mfunc11on
exJoadsave2-14Vorklng wllh MAlLAB Dolo Flles slng Lood ond Sove
Th1s exanpJe shoWs hoW 1o Work W11h 1he "Joad1save" func11ons on
da1a f1Jes 1n depJoyed node. There are 1hree source da1a f1Jes 1n
1h1s exanpJe. userda1a.na1 userda1a1ex1rada1a.na1
..1ex1ernda1a1ex1ernda1a.na1 Conp1Je 1h1s exanpJe W11h 1he ncc
connand: ncc -nC exJoadsave.n -a `userda1a.na1` -a
`.1userda1a1ex1rada1a.na1` -a `..1ex1ernda1a1ex1ernda1a.na1` AJJ
1he foJders under 1he curren1 na1n MATLA8 f1Je d1rec1ory W1JJ be
1ncJuded as reJa11ve pa1h 1o c1froo1 AJJ o1her foJders W1JJ have
1he foJder s1ruc1ure 1ncJuded 1n 1he c1f arch1ve f1Je fron roo1 of
1he d1sk dr1ve. 1f a da1a f1Je 1s ou1s1de of 1he na1n MATLA8 f1Je
pa1h. 1he absoJu1e pa1h W1JJ be 1ncJuded 1n c1f and ex1rac1ed under
c1froo1. For exanpJe: 0a1a f1Je
"c:`$na1Jabroo1`exanpJes`ex1ernda1a`ex1ernda1a.na1" W1JJ be added
1n1o c1f and ex1rac1ed 1o
"$c1froo1`$na1Jabroo1`exanpJes`ex1ernda1a`ex1ernda1a.na1". AJJ
na11da1a f1Jes are unchanged af1er ncc runs. There 1s no excryp11on
on 1hese user 1ncJuded da1a f1Jes. They are 1ncJuded 1n 1he c1f
arch1ve. The 1arge1 da1a f1Je 1s: .1ou1pu11savedda1a.na1 When
Wr111ng 1he f1Je 1o JocaJ d1sk. do no1 save any f1Jes under c1froo1
s1nce 11 nay be refreshed and deJe1ed When 1he appJ1ca11on 1snex1
s1ar1ed.==== Joad da1a f1Je =============================1f
1sdepJoyed 1n depJoyed node. aJJ f1Je under CTFPoo1 1n 1he pa1h are
Joaded2-152 Vrlllng Deployoble MAlLABCode by fuJJ pa1h nane or
reJa11ve 1o $c1froo1.
L0A0F1LENAME1=Wh1ch{fuJJf1Je{c1froo1.nf1Jenane.`userda1a.na1`))
L0A0F1LENAME2=Wh1ch{fuJJf1Je{c1froo1.`userda1a`.`ex1rada1a.na1`))L0A0F1LENAME1=Wh1ch{fuJJf1Je{`userda1a.na1`))L0A0F1LENAME2=Wh1ch{fuJJf1Je{`ex1rada1a.na1`))
For ex1ernaJ da1a f1Je. fuJJ pa1h W1JJ be added 1n1o c1f you don`1
need spec1fy 1he fuJJ pa1h 1o f1nd 1he
f1Je.L0A0F1LENAME3=Wh1ch{fuJJf1Je{`ex1ernda1a.na1`))eJserunn1ng 1he
code 1n
MATLA8L0A0F1LENAME1=fuJJf1Je{na1Jabroo1.`ex1ern`.`exanpJes`.`conp1Jer`.`0a1aRandJ1ng`.`userda1a.na1`)L0A0F1LENAME2=fuJJf1Je{na1Jabroo1.`ex1ern`.`exanpJes`.`conp1Jer`.`0a1aRandJ1ng`.`userda1a`.`ex1rada1a.na1`)L0A0F1LENAME3=fuJJf1Je{na1Jabroo1.`ex1ern`.`exanpJes`.`conp1Jer`.`ex1ernda1a`.`ex1ernda1a.na1`)end
Load 1he da1a f1Je fron curren1 Work1ng d1rec1oryd1sp{|`Load A fron
: `.L0A0F1LENAME1])Joad{L0A0F1LENAME1.`da1a1`)d1sp{`A=
`)d1sp{da1a1) Load 1he da1a f1Je fron sub d1rec1oryd1sp{|`Load 8
fron : `.L0A0F1LENAME2])Joad{L0A0F1LENAME2.`da1a2`)d1sp{`8=
`)d1sp{da1a2) Load ex1ern da1a ou1s1de of curren1 Work1ng
d1rec1oryd1sp{|`Load ex1ern da1a fron :
`.L0A0F1LENAME3])Joad{L0A0F1LENAME3)d1sp{`ex1da1a=
`)d1sp{ex1da1a)==== nuJ11pJe 1he da1a na1r1x by 2
==============resuJ1 = da1a1*da1a2d1sp{`A * 8 =
`)d1sp{resuJ1)2-16Vorklng wllh MAlLAB Dolo Flles slng Lood ond
Sove==== save 1he neW da1a 1o a neW f1Je
===========SAvEPATR=s1rca1{pWd.f1Jesep.`ou1pu1`)1f {
-1sd1r{SAvEPATR))nkd1r{SAvEPATR)endSAvEF1LENAME=s1rca1{SAvEPATR.f1Jesep.`savedda1a.na1`)d1sp{|`Save
1he A * 8 resuJ1 1o : `.SAvEF1LENAME])save{SAvEF1LENAME.
`resuJ1`)2-172 Vrlllng Deployoble MAlLABCode2-183ProgrammingTo
access a Java component built and packaged by the MATLAB Builder
JAproduct, you must first unpackage and install components so you
can usethem on a particular machine. See Chapter 1, Getting Started
for moreinformation.* About the MATLAB Builder JA API on page 3-3*
Importing Classes on page 3-8* Creating an Instance of the Class on
page 3-9* Passing Arguments to and from Java on page 3-13* Passing
Java Objects by Reference on page 3-27* Handling Errors on page
3-34* Managing Native Resources on page 3-40* Improving Data Access
Using the MCR User Data Interface andMATLAB Builder JA on page
3-44* Dynamically Specifying Run-Time Options to the MCR on page
3-49* Handling Data Conversion Between Java and MATLAB on page
3-52* Setting Java Properties on page 3-54* Blocking Execution of a
Console Application that Creates Figures onpage 3-56* Ensuring
Multi-Platform Portability on page 3-59* Using MCR Component Cache
and MWComponentOptions on page 3-61* Learning About Java Classes
and Methods by Exploring the Javadocon page 3-643 ProgrommlngNole
For examples of these tasks, see Chapter 4, Sample Java
Applications.For information about deploying your application after
you complete thesetasks, see How Does Component Deployment Work? on
page 1-3.3-2Aboul lhe MAlLABBullder" !A APlAboul lhe MAILA8 8uilder
JA APlln lhis seclion...Understanding the MATLAB Builder JA API
Data Conversion Classeson page 3-3Automatic Conversion to MATLAB
Types on page 3-4Understanding Function Signatures Generated by the
MATLAB BuilderJA Product on page 3-5Adding Fields to Data
Structures and Data Structure Arrays on page 3-6Returning Data from
MATLAB to Java on page 3-7Underslonding lhe MAILA8 8uilder JA APl
DoloConversion ClossesWhen writing your Java application, you can
represent your data usingobjects of any of the data conversion
classes. Alternatively, you can usestandard Java data types and
objects.The data conversion classes are built as a class hierarchy
that represents themajor MATLAB array types.Nole This discussion
provides conceptual information about the classes.For details, see
con.na1hWorks.1ooJbox.]avabu1Jder in the productDocumentation
Set.This discussion assumes you have a working knowledge of the
Javaprogramming language and the Java Software Developers Kit
(SDK). Thisis not intended to be a discussion on how to program in
Java. Refer to thedocumentation that came with your Java SDK for
general programminginformation.3-33 ProgrommlngOverview ol Closses
ond Melhods in lhe Dolo ConversionCloss HierorchyThe root of the
data conversion class hierarchy is the MWArray abstractclass. The
MWArray class has the following subclasses representing themajor
MATLAB types: MWNuner1cArray, MWLog1caJArray,
MWCharArray,MWCeJJArray, and MWS1ruc1Array.Each subclass stores a
reference to a native MATLAB array of that type.Each class provides
constructors and a basic set of methods for accessingthe underlying
arrays properties and data. To be specific, MWArray and theclasses
derived from MWArray provide the following:* Constructors and
finalizers to instantiate and dispose of MATLAB arrays* ge1 and se1
methods to read and write the array data* Methods to identify
properties of the array* Comparison methods to test the equality or
order of the array* Conversion methods to convert to other data
typesAdvonloge ol Using Dolo Conversion ClossesThe MWArray data
conversion classes let you pass native type parametersdirectly
without using explicit data conversion. If you pass the same
arrayfrequently, you might improve the performance of your program
by storingthe array in an instance of one of the MWArray
subclasses.Aulomolic Conversion lo MAILA8 IypesNole Because the
conversion process is automatic (in most cases), you do notneed to
understand the conversion process to pass and return arguments
withMATLAB Builder JA components.When you pass an MWArray instance
as an input argument, the encapsulatedMATLAB array is passed
directly to the method being called.In contrast, if your code uses
a native Java primitive or array as an inputparameter, the builder
converts it to an instance of the appropriate MWArray3-4Aboul lhe
MAlLABBullder" !A APlclass before it is passed to the method. The
builder can convert any Javastring, numeric type, or any
multidimensional array of these types to anappropriate MWArray
type, using its data conversion rules. See DataConversion Rules on
page 8-8 for a list of all the data types that aresupported along
with their equivalent types in MATLAB.The conversion rules apply
not only when calling your own methods, butalso when calling
constructors and factory methods belonging to the
MWArrayclasses.Nole There are some data types commonly used in
MATLAB that arenot available as native Java types. Examples are
cell arrays and arrays ofcomplex numbers. Represent these array
types as instances of MWCeJJArrayand MWNuner1cArray,
respectively.Underslonding Funclion 5ignolures Generoled by
lheMAILA8 8uilder JA ProduclThe Java programming language now
supports optional function argumentsin the way that MATLAB does
with vararg1n and varargou1. To support thisfeature of MATLAB, the
builder generates a single overloaded Java methodthat accommodates
any number of input arguments. This behavior is anenhancement over
previous versions of vararg1n support that only handled alimited
number of arguments.Nole In addition to handling optional function
arguments, the overloadedJava methods that wrap MATLAB functions
handle data conversion. SeeAutomatic Conversion to MATLAB Types on
page 3-4 for more details.Underslonding MAILA8 Funclion
5ignoluresAs background, recall that the generic MATLAB function
has the followingstructure:func11on |0u11. 0u12. ....
varargou1]=foo{1n1. 1n2. .... vararg1n)3-53 ProgrommlngTo the left
of the equal sign, the function specifies a set of explicit and
optionalreturn arguments.To the right of the equal sign, the
function lists explicit input argumentsfollowed by one or more
optional arguments.Each argument represents a MATLAB type. When you
include the vararg1nor varargou1 argument, you can specify any
number of inputs or outputsbeyond the ones that are explicitly
declared.Overlooded Melhods in Jovo Ihol Encopsulole MAILA8
CodeWhen the MATLAB Builder JA product encapsulates your MATLAB
code, itcreates an overloaded method that implements the MATLAB
functions. Thisoverloaded method corresponds to a call to the
generic MATLAB function foreach combination of the possible number
and type of input arguments.In addition to encapsulating input
arguments, the builder creates anothermethod, which represents the
output arguments, or return values, of theMATLAB function. This
additional overloaded method takes care of returnvalues for the
encapsulated MATLAB function. This method of encapsulatingthe
information about return values simulates the nJx interface in
theMATLAB Compiler product.These overloaded methods are called the
standard interface (encapsulatinginput arguments) and the nJx
interface (encapsulating return values). SeeProgramming Interfaces
Generated by the MATLAB Builder JA Producton page 8-12 for
details.Adding Fields lo Dolo 5lruclures ond Dolo
5lruclureArroysWhen adding field