User manual MATLAB MATLAB BUILDER JA 2

[. . . ] MATLAB® BuilderTM JA 2 User's Guide How to Contact The MathWorks Web Newsgroup www. mathworks. com/contact_TS. html Technical Support www. mathworks. com comp. soft-sys. matlab suggest@mathworks. com bugs@mathworks. com doc@mathworks. com service@mathworks. com info@mathworks. com Product enhancement suggestions Bug reports Documentation error reports Order status, license renewals, passcodes Sales, pricing, and general information 508-647-7000 (Phone) 508-647-7001 (Fax) The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098 For contact information about worldwide offices, see the MathWorks Web site. MATLAB® BuilderTM JA User's Guide © COPYRIGHT 2006­2010 by The MathWorks, Inc. The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. [. . . ] It is common practice to include any cleanup code that must execute before leaving the function in a finally block. The documentation examples use finally blocks in all the code samples to free native resources that were allocated in the method. For more information on freeing resources, see "Managing Native Resources" on page 3-40. Code Fragment: Handling an Exception in the Calling Function In this next example, the method that calls myprimes declares that it throws an MWException: public double[] getprimes(int n) throws MWException { myclass cls = null; Object[] y = null; 3-36 Handling Errors try { cls = new myclass(); y = cls. myprimes(1, new Double((double)n)); return (double[])((MWArray)y[0]). getData(); } finally { MWArray. disposeArray(y); if (cls != null) cls. dispose(); } } Handling Unchecked Exceptions Several types of unchecked exceptions can also occur during the course of execution. Unchecked exceptions are Java exceptions that do not need to be explicitly declared with a throws clause. The MWArray API classes all throw unchecked exceptions. All unchecked exceptions thrown by MWArray and its subclasses are subclasses of java. lang. RuntimeException. The following exceptions can be thrown by MWArray: · java. lang. RuntimeException · java. lang. ArrayStoreException · java. lang. NullPointerException · java. lang. IndexOutOfBoundsException · java. lang. NegativeArraySizeException This list represents the most likely exceptions. Others might be added in the future. 3-37 3 Programming Code Fragment: Catching General Exceptions You can easily rewrite the getprimes example to catch any exception that can occur during the method call and data conversion. Just change the catch clause to catch a general java. lang. Exception. public double[] getprimes(int n) { myclass cls = null; Object[] y = null; try { cls = new myclass(); y = cls. myprimes(1, new Double((double)n)); return (double[])((MWArray)y[0]). getData(); } /* Catches the exception thrown by anyone */ catch (Exception e) { System. out. println("Exception: " + e. toString()); return new double[0]; } finally { MWArray. disposeArray(y); if (cls != null) cls. dispose(); } } Code Fragment: Catching Multiple Exception Types This second, and more general, variant of this example differentiates between an exception generated in a compiled method call and all other exception types by introducing two catch clauses as follows: public double[] getprimes(int n) { 3-38 Handling Errors myclass cls = null; Object[] y = null; try { cls = new myclass(); y = cls. myprimes(1, new Double((double)n)); return (double[])((MWArray)y[0]). getData(); } /* Catches the exception thrown by myprimes */ catch (MWException e) { System. out. println("Exception in MATLAB call: " + e. toString()); return new double[0]; } /* Catches all other exceptions */ catch (Exception e) { System. out. println("Exception: " + e. toString()); return new double[0]; } finally { MWArray. disposeArray(y); if (cls != null) cls. dispose(); } } The order of the catch clauses here is important. Because MWException is a subclass of Exception, the catch clause for MWException must occur before the catch clause for Exception. If the order is reversed, the MWException catch clause will never execute. 3-39 3 Programming Managing Native Resources In this section. . . "What Are Native Resources?" on page 3-40 "Using Garbage Collection Provided by the JVM" on page 3-40 "Using the dispose Method" on page 3-41 "Overriding the Object. Finalize Method" on page 3-43 What Are Native Resources? When your code accesses Java classes created by the MATLAB Builder JA product, your program uses native resources, which exist outside the control of the Java Virtual Machine (JVM). Specifically, each MWArray data conversion class is a wrapper class that encapsulates a MATLAB mxArray. The encapsulated MATLAB array allocates resources from the native memory heap. Note Native arrays should always be explicitly freed. Because the Java wrapper is small and the mxArray is relatively large, the JVM memory manager may not call the garbage collector before the native memory becomes exhausted or badly fragmented. Using Garbage Collection Provided by the JVM When you create a new instance of a Java class, the JVM allocates and initializes the new object. When this object goes out of scope, or becomes otherwise unreachable, it becomes eligible for garbage collection by the JVM. The memory allocated by the object is eventually freed when the garbage collector is run. When you instantiate MWArray classes, the encapsulated MATLAB also allocates space for native resources, but these resources are not visible to the JVM and are not eligible for garbage collection by the JVM. These resources are not released by the class finalizer until the JVM determines that it is appropriate to run the garbage collector. 3-40 Managing Native Resources The resources allocated by MWArray objects can be quite large and can quickly exhaust your available memory. To avoid exhausting the native memory heap, MWArray objects should be explicitly freed as soon as possible by the application that creates them. Using the dispose Method The best technique for freeing resources for classes created by the MATLAB Builder JA product is to call the dispose method explicitly. Any Java object, including an MWArray object, has a dispose method. [. . . ] Specify java: to create a Java component. Specifies the name of the component and its namespace, which is a period-separated list, such as companyname. groupname. component. component_name 9-4 mcc -W String Elements class_name Description Specifies the name of the Java class to be created. The default class_name is the last item in the list specified as component_name. file1 [file2. . . fileN] are MATLAB files to be encapsulated as methods in class_name. [. . . ]