%% MatlabHelpJava.txt %% %% modified 'help java' output provided from MATLAB 5.3 command line. %% %% 14 MAY 99, Don Brutzman %% %% warning! note that ISJAVA, JAVA_OBJECT and JAVA_METHOD are actually used %% in lowercase, i.e. isjava, java_object and java_method in your matlab files. %% %% Install Java JDK 1.2 (which works) or 1.1.8 (which they use) on your box %% each available from http://www.javasoft.com/nav/download %% %% Then install the Recursive Ray Acoustics (RRA) package, available from %% http://devo.stl.nps.navy.mil/~brutzman/vrtp/rra %% %% Then update MATLAB's classpath file as follows: %% » which classpath.txt %% D:\MATLABR11\toolbox\local\classpath.txt %% » edit D:\MATLABR11\toolbox\local\classpath.txt %% expose the mil.navy.nps.rra.* classes by appending 'c:\vrtp' to that file %% %% I also installed Internet Explorer 5 on top of NT 4 Service Pack 4 %% to ensure Microsoft Java works properly, though running msjavx86.exe %% as they recommend is probably sufficient. Your mileage may vary. %% %% Comments/questions/problems/suggestions are welcome. %% I will maintain and send our buglists to Matlab. » help java Using Java from within MATLAB ----- WARNING ----- This Java interface is experimental and unsupported in this release. It is very likely that this interface will change in the next release so you should not develop code that depends on this experimental interface remaining stable from release to release. We expect to make a Java interface a fully supported feature in a future release. ----- WARNING ----- By default, Java is not enabled in MATLAB. To activate Java you must issue the following command at the MATLAB prompt: >> java on You can construct Java objects from within MATLAB by using the name of the class to instantiate: >> f = java.awt.Frame('My Title') f = java.awt.Frame[frame0,0,0,0x0,invalid,hidden,layout=java.awt.BorderLayout,resizable,title=my title] You can call methods of Java objects using either Matlab syntax: >> setTitle ( f , ' new title' ) or Java syntax: >> t = f.getTitle t = new title In this case f is the java.awt.Frame object created above, and getTitle and setTitle are methods of that object. Examples of using Java from within MATLAB Here are three examples of doing simple tasks using Java from within MATLAB. You can paste these examples directly into the command line. This section is NOT intended to teach you Java. We assume you are already familiar with Java or will learn it elsewhere. MATLAB does not have the equivalent of the Java import statement so you must type the full "package name" of the classes you use. That is, "java.awt.Frame" instead of just "Frame". Example 1: Read a URL This example opens a connection to a URL at NCSA. It then reads and echoes the first 100 lines from the file. java on % enable Java url = java.net.URL(' http://www.ncsa.uiuc.edu/demoweb/url-primer.html ') is = openStream(url) isr = java.io.InputStreamReader(is) br = java.io.BufferedReader(isr) for i = 1:100 s = readLine(br) end Example 2: AWT GUI This example uses Java AWT components to build a very simple GUI. Notice that this GUI doesn't do anything. For that you would have to write and connect event listeners, a task beyond the scope of this example. java on % Enable Java. % Define the different font weights. font_plain = 0; font_bold = 1; font_italic = 2; % Define some fonts and colors. f1 = java.awt.Font('TimesRoman', font_plain, 18); c1 = java.awt.Color(1,0.5,0); f2 = java.awt.Font('TimesRoman', font_bold, 15); c2 = java.awt.Color(0.5,0.1,1); f3 = java.awt.Font('TimesRoman', font_italic, 13); c3 = java.awt.Color(0,0.25,0); % Create a frame, a panel and button. frame = java.awt.Frame('A Sample Frame'); panel = java.awt.Panel; button1 = java.awt.Button('Continue'); setBackground(frame,java.awt.Color(0.9, 0.8, 0.5)); setFont(button1, f1); setForeground(button1, c1); setBackground(button1, java.awt.Color(0.5,0.25,0.25)); % Add the panel to the center of the frame. add(frame, 'Center', panel); % Add the button to the bottom of the frame. add(frame, 'South', button1); % Add padding to the edges of the frame. add(frame, 'North', java.awt.Label); add(frame, 'East', java.awt.Label); add(frame, 'West', java.awt.Label); % Define a 2-by-2 grid layout for the center panel. setLayout(panel, java.awt.GridLayout(2,2,15,30)); % Create static text and editable text boxes. label1 = java.awt.Label('Enter your name:'); text1 = java.awt.TextField('Jack',45); label2 = java.awt.Label('Enter your password:'); text2 = java.awt.TextField(45); setEchoChar(text2, '*'); % Add the first label and editable text box to the panel. setFont(label1, f2); setForeground(label1, c2); add(panel, label1); add(panel, text1); % Add the second label and editable text box to the panel. setFont(label2, f3); setForeground(label2, c3); add(panel, label2); add(panel, text2); % Display the frame. setSize(frame, 300, 170); setVisible(frame, 1) Example 3: Create and run an ActiveX control This example will only work on a PC since it uses the Microsoft specific class "com.ms.activeX.ActiveXControl". If you don't have the mscal ocx on your machine you can supply the "guid" of the control of your choice. java on % enable Java f = java.awt.Frame('An ActiveX Control') % make a window mscal = com.ms.activeX.ActiveXControl('{8E27C92B-1264-101C-8A2F-040224009C02}') add(f,'Center',mscal) % put the control in the window setSize(f,600,500) % size the window setVisible(f,1) % make the window visible setProperty(mscal,'month',3) % my birthday setProperty(mscal,'day',16) showPropertyDialog(mscal) % open the property dialog Changed and enhanced built-in functions The METHODS function now accepts the -full qualifier. The -full qualifier will cause METHODS to return a full description of all methods instances in a Java class, including method signatures and other information relevant to use of the methods in a Java class. METHODS without -full will return the compact methods listing with all duplicate method names removed. The ISA function now accepts full and partial Java class names. For example, isa(x, 'java.awt.Frame'), isa(x, 'awt.Frame'), and isa(x, 'Frame'). The CLASS function has been enhanced to return the Java class name of Java object arrays. INMEM has been enhanced to accept an optional third argument output. If supplied, this third argument will return a list of all Java classes loaded. WHICH will search all loaded Java classes for methods that match the argument string. New built-in functions ISJAVA True for Java object arrays ISJAVA(J) returns 1 if J is a Java object array, and 0 otherwise. JAVA_OBJECT Invoke a Java object constructor If C is a string containing the name of a Java class, then JAVA_OBJECT(C,x1,...,xn) invokes the Java constructor for class C with the signature matching the arguments x1,...,xn. The resulting Java object is returned as a Java object array. For example, X = JAVA_OBJECT('java.awt.Color', 0, 0, 200); will construct and return a java.awt.Color object array. If a constructor matching the specified class and signature does not exist, an error will occur. JAVA_OBJECT will not normally be needed or used; the usual way to invoke Java constructors is by the MATLAB constructor syntax, such as X = java.awt.Color(0, 0, 200); for the example above. JAVA_OBJECT is provided for those instances that the MATLAB constructor syntax cannot be used (such as when parametric object construction is required). JAVA_METHOD Invoke a Java method JAVA_METHOD is the only mechanism provided by MATLAB to invoke static Java methods. It may also be used to invoke non-static Java methods. If M is a string containing the name of a Java method, and C is a string containing the name of a Java class, then JAVA_METHOD(M,C,x1,...,xn) will invoke the Java method M in the class C with the signature matching the arguments x1,...,xn. For example, JAVA_METHOD('isNan','java.lang.Double',x) will invoke the static Java method isNan in class java.lang.Double. This is the way to invoke static Java methods from MATLAB. If J is a Java object array, then JAVA_METHOD(M,J,x1,...xn) will invoke the non-static Java method M in the class of J with the signature matching the arguments x1,...xn. For example, if F is a java.awt.Frame Java object array, then JAVA_METHOD('setTitle', F, 'New Title') will set the title of for the frame. JAVA_METHOD will not normally be needed or used in this form; the usual way to invoke Java methods on a Java object is by the MATLAB method invocation syntax, such as setTitle(F, 'New Title'); JAVA_METHOD is provided for those instances when the MATLAB method invocation syntax cannot be used (such as when complete control is required). Making new Java classes MATLAB will allow you to use any existing java classes. If you want to create and use your own Java classes, you will need to get a Java development environment. There are many commercially available products. MATLAB uses version 1.1 of Java, so be sure to get an environment that supports Java 1.1 (not Java 1.0, or 1.2). On the PC, MATLAB uses Microsoft's SDK for Java version 2 (That's SDK version 2, which is a Java 1.1 environment) which can be downloaded from Microsoft (www.microsoft/java). Sun's Javasoft site (www.javasoft.com) has Java environments for Windows machines and Sun workstations, and pointers to many Java resources. Choose "Products & API's" to find the Java Development Kit 1.1. Both of these sites provide documentation of the Java language and classes. You will need their documentation to use Java since The MathWorks does not provide it. Use your Java compiler to produce .class files from your .java files. For MATLAB to see your classes they must be in a directory on MATLAB's classpath (that's classpath, NOT MATLABPATH). MATLAB's classpath is kept in a file called classpath.txt in your toolbox/local directory (type which classpath.txt at the MATLAB prompt.) Add the full path to the directory containing your .class files to this file. Classpath.txt is only read once when MATLAB starts, so changes to it or your .class files require you to restart MATLAB before they will take effect. How MATLAB determines which Java method to invoke MATLAB arguments passed to a java method are matched with Java method signatures. Any signatures which have the wrong number of arguments are immediately rejected. The table below is used to decide which of the remaining signatures are valid. A Java method signature will be assigned a fitness value according to how well the types of its arguments match the MATLAB input arrays. Any signature containing incompatible argument types will be rejected. The remaining method signature with the highest fitness value will be chosen. The fitness value is the sum of the fitness values for all argument types. The fitness value for each argument is the fitness of the base type minus the difference between the MATLAB dimension and the Java dimension. In MATLAB, dimension is the number of non-singleton dimensions in the array. For example, a 10x1 array would be of dimension 1, and a 1x1 array would be of dimension 0. In Java, dimension is determined solely by the number of nested arrays. For example, "double[][]" would be of dimension 2, and "double" would be of dimension 0. If two method signatures have the same fitness, the first one defined in the Java class is chosen. The empty matrix is compatible with any method argument for which null is a legal value in Java. The empty string ('') in MATLAB translates into an empty (not null) String object in Java. Matlab Java Highest Priority Lowest Priority --------------------------------------------------------------------------------------- logical boolean double double float long int short byte boolean single float double char String char cell array of strings String cell array Object uint8 byte short int long float double uint16 short int long float double uint32 int long float double int8 byte short int long float double int16 short int long float double int32 int long float double java Object Return Arguments are converted from Java types to MATLAB types according to the table below. A null object returned from Java is converted to the empty matrix ([]) in MATLAB. Java Matlab --------------------- boolean logical byte int8 char char short int16 int int32 long double float single double double String char Object Java Known Restrictions and Limitations You have to exit MATLAB in order to unload loaded classes. Java object arrays cannot be saved to MAT-files. Java in MATLAB works only on PCs running Windows and Suns running Solaris in this release. If you get errors saying "MATLAB is unable to start the virtual machine" then Java is most likely not installed on your machine. Installing MATLAB does not automatically install Java on your machine. If you do not already have Java installed, you can install it on a PC by running "msjavx86.exe" from your Matlab bin directory. It will ask you if you want to install Java support for Internet Explorer. Press Yes, It will install Java, not Internet Explorer. On a Sun workstation, you'll have to download and install the "JRE" (Java Runtime Environment) from Sun at www.javasoft.com.