Quick Start: Implementing a Custom WebFigure

MATLAB Programmer

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

Role

Knowledge Base

Responsibilities

MATLAB programmer

MATLAB expert
No IT experience
No access to IT systems

Develops models; implements in MATLAB
Uses tools to create a component that is used by the Java developer

Java Developer

Role	Knowledge Base	Responsibilities
Java developer	Little to no MATLAB experience Moderate IT Experience Java expert Minimal access to IT systems	Integrates deployed component with the rest of the Java application Integrates deployed MATLAB Figures with the rest of the Java application

Role

Knowledge Base

Responsibilities

Java developer

Little to no MATLAB experience
Moderate IT Experience
Java expert
Minimal access to IT systems

Integrates deployed component with the rest of the Java application
Integrates deployed MATLAB Figures with the rest of the Java application

Overview

By following the Quick Start procedure, both the WebFigure service and the page that has the WebFigure embedded in it will be set up to reside on a single server. This configuration allows you to quickly reference your WebFigure from a JSP page with minimal configuration.

Setting Up the Web Server

Ensure that your Web server is properly configured with the required components by performing these steps:

Install and Configure Apache® Tomcat™

Download Apache Tomcat from the Apache Web site.
Install the product using an available port number. Note the port number you choose for future reference.
Navigate to C:\Program Files\Apache Software Foundation\Tomcat x.x\conf.
Using a text editor, edit tomcat-users.xml.
Browse to find the section listing sample users and roles, usually at the end of the file:
Tomcat Role and User Listing in tomcat-users.xml
Remove comments from all the role and user statements (<!.. ..>).
Modify the <user statement, customizing it with a username and password of your choice. In the example above, the chosen username is admin and the password is borg. The roles= parameter assigns specific roles and accorded privileges to this user, defined earlier in the <role statements. See the Apache Tomcat documentation for further information regarding users and roles.
Save and close tomcat-users.xml.
Open a browser session and enter this URL:
```
http://localhost:port_number/
```
For example, if you chose port number 8080 when you installed Tomcat, you would enter: http://localhost:8080/. An image similar to the following should appear:

This image indicates that you have successfully set up Apache Tomcat.

Install `javabuilder.jar`

From MATLAB, navigate to the folder: C:\Program Files\MATLAB\release_name\toolbox\javabuilder\jar\.
From this folder, copy javabuilder.jar to C:\Program Files\Apache Software Foundation\Tomcat x.x\lib. By doing this, you are adding the MATLAB Builder JA JAR file to Apache Tomcat folder of global JARs.

Install the Web Archive (WAR)

In the browser session you started in Install and Configure Apache® Tomcat™, click the Manager App button, displayed in the above screenshot.
On the Tomcat Web Application Manager page, find the section WAR File to Deploy:
To the right of the field Select WAR file to upload, click Browse.
Navigate to the folder C:\Program Files\MATLAB\release_name\toolbox\javabuilder\jar\ and select WebFigureQuickStart.war.
In the WAR File to Deploy section, click Deploy.
WebFigureQuickStart should now be listed in the Applications section of the Tomcat Web Application Manager page:

You are now ready to create your first WebFigure.

Creating the Default WebFigure

Start up your Web server.
Open a browser and navigate to the JSP file contained in the WebFigureQuickStart application. If you are running this locally, the URL is:
http://hostName:portNumber/WebFigureQuickStart/WebFigureExample.jsp
The following default figure page appears:

Behind the Scenes: How a WebFigure Is Referenced

The Web application that MathWorks ships contains a reference to a servlet in WebFigureQuickStart.war (installed in Setting Up the Web Server). The JSP file instantiates a deployed component that is also in WebFigureQuickStart.war and attaches it to the application scope of the server. It uses the JSP tag to reference the figure on the page.

Interacting with the Default WebFigure

Interact with the default figure on the page using your mouse:

Click one of the three control icons at the top of the figure to select the desired control.
Select the region of the figure you want to manipulate.
Click and drag to manipulate the figure. For example, to zoom in the figure, click the magnifying glass icon, then hover over the figure.

Creating a Custom WebFigure

After you access the default figure, add one of your own figures:

Ensure you have done the following with the MATLAB code referenced in Assumptions About the Examples (or your own MATLAB code):
- Tested the code
- Compiled the code using MATLAB Builder JA
- Successfully generated the yourcomponent.jar file from the compilation.
For more information on this process, please see Getting Started in this guide.
Test to ensure that your Web server is functioning. You can do this by creating a JSP Web page, deploying it to your server, and then attempting to access it.

Create a new Web application and an associated JSP file within that application. In the web.xml file for your Web application (in the WEB-INF folder in a Web application), add the following reference to the built-in WebFigureServlet:

<servlet>
  <servlet-name>WebFigures</servlet-name>
  <servlet-class>
		com.mathworks.toolbox.javabuilder.webfigures.WebFiguresServlet
	</servlet-class>
</servlet>
<servlet-mapping>
    <servlet-name>WebFigures</servlet-name>
    <url-pattern>/WebFigures/*</url-pattern>
</servlet-mapping>

Copy MATLABROOT/toolbox/javabuilder/webfigures/webfigures.tld, the WebFigures customer tag handler file, to the WEB-INF folder under your Web application directory.
In the JSP file, add a reference to the WebFigure tag by including the following line of code at the beginning of the file. The URI listed here is for example purposes only.
```
<%@ taglib 
   prefix="wf" 
   uri="http://www.mathworks.com/builderja/webfigures.tld" 
%>
```
Add an actual WebFigure tag in the body of the page:
```
<wf:web-figure />
```
At this point, test that the configuration is working properly following the changes you previously made. By having an empty WebFigure tag, the WebFigureService automatically displays the default WebFigure and the resulting page should resemble that achieved in Creating the Default WebFigure.
Reference the previously built and deployed component from your JSP page:
1. Add the following import statement to your JSP page:
```
<%@ page import="yourComponentsPackage.YourComponentsClass" %>
```
2. Add the following import statement to invoke the WebFigure:
```
<%@ page import="com.mathworks.toolbox.javabuilder.webfigures.WebFigure" %> 
```
3. c. Add the following statement to enable access to MWJavaObjectRef:
```
<%@ page import="com.mathworks.toolbox.javabuilder.*" %> 
```

Instantiate the deployed component and call the method that will return the WebFigure, as in this sample code:

<%
		MyComponentClass myDeployedComponent = null;
    try {
    		//Instantiate the Deployed Component
    		myDeployedComponent = new MyComponentClass();

       try {
       		WebFigure webFigure = (WebFigure)
                  ((MWJavaObjectRef)myDeployedComponent.getKnot(1)[0]).get();

             //Get the WebFigure from your function's output 
             //   and set it to the tag
             request.getSession().setAttribute("YourFigure", webFigure);
       }
       catch(ClassCastException e)
       {
       		throw new Exception
                       ("
      Issue casting deployed components outputs to WebFigure", e);
                        }
		}
    catch (Exception e) {
    		e.printStackTrace();
   	}
    finally {
    	  	//Dispose of the Deployed Component 
         // (necessary since this has native resources).
       myDeployedComponent.dispose();
   	}
%>
<wf:web-figure name="YourFigure" scope="session"/>