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

%   $Revision: 1.6.1.3 $  $Date: 1999/01/21 16:27:46 $
%   Copyright (c) 1984-99 by The MathWorks, Inc.
