Advanced Configuration of a WebFigure

On this page…
Overview How Do WebFigures Work? Installing WebFigureService Getting the WebFigure Object from Your Method Attaching a WebFigure Using the WebFigure JSP Tag to Reference a WebFigure Getting an Embeddable String That References a WebFigure Attached to a Cache

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

Overview

The advanced configuration gives the experienced Java developer (possibly a business service developer or front-end developer) flexibility and control in configuring system architecture based on differing needs. For example, with the WebFigureService and the Web page on different servers, the administrator can optimally position the MCR (for performance reasons) or place customer-sensitive customer data behind a security firewall, if needed.

This section describes various ways to customize the basic WebFigures implementation described in Quick Start: Implementing a Custom WebFigure.

The advanced configuration offers more choices and adaptability for the user more familiar with Web environments and related technology, as illustrated by the following graphics.

Back to Top

How Do WebFigures Work?

When choosing the best architecture for your configuration, it is important to understand the fundamental components that enable an application.

WebFigures is made up of several different components that work together:

• Your Web application

• Client-side code

• WebFigureService

• Your server's cache

When you enable a user to rotate a figure, for example, you are using standard AJAX techniques to request different static images depending on the requested orientation. WebFiguresService (which is exposed by referencing WebFigureServlet in web.xml) delivers the HTML and JavaScript™ to a browser, getting the defaults for a figure, and rendering a figure in any of its available orientations.

Your Web application calls one of your deployed components to get the specific WebFigure, and attaches it to your server's cache for WebFiguresService to use later. Your application also puts an HTML reference to your WebFigure on a page. This can either be done automatically using the JSP tag or manually by using WebFigureHtmlGenerator. This gives the client browser what it needs to request the client-side code.

The client-side JavaScript™ AJAX code provides a user experience similar to that in MATLAB when using a FIGURE. It provides rotation, zooming, and panning in a highly usable medium by using a JavaScript application that monitors for user interaction such as dragging or clicking with a mouse, and calls back into WebFiguresService to service those requests.

For example, when a user selects the rotate icon and clicks in the WebFigureTag and drags it, that drag translates to coordinates and issues a request for the new rotated image from WebFiguresService. A rotating cube is displayed so the user knows what orientation they are looking at. Since there is no efficient way to pass an actual WebFigure from your application to the client-side application and then back to WebFiguresService, the server's built-in cache is leveraged as a central repository.

Back to Top

Installing WebFigureService

In order for the client-side code to call back to request images, you need a reference to the built-in servlet in the application's web.xml file. This reference should look like this:

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

Note   You can rename the servlet and its mapping. If you do, you must reference it whenever you interact with either the WebFigureHtmlGenerator or the JSP tag (using the root attribute) so it can call back to the servlet. It is critical that the URL pattern you map to ends with the literal /*. This allows all end points to be redirected to the servlet. To test this end point at any time, navigate to it in a browser and you should see the default Web page. If you have web.xml set correctly in your application, the URL will look something like http://hostName:portNumber/yourWebApplication/WebFigures.

Back to Top

Getting the WebFigure Object from Your Method

Once you have a deployed component created using WebFigures returned by a MATLAB method, you need to access that object.

In MATLAB Builder JA, when a WebFigure Java Object is created in MATLAB code and returned, you convert that MWJavaObjectRef into a regular WebFigure in order to access it. For example:

try
{
       Object[] results = null;
       try
       {
              //This assumes there is only a single option 
              // from your function
              //  and it has no inputs.
              results = myDeployedComponent.getSurfPeaks(1);
              
              //Since we know the only output is the WebFigure 
              // we get the MWJavaObjectRef from 
              //    the Object Array. 
              //By calling "get" on the MWJavaObjectRef we 
              // retrieve the 
              //  actual object from it.
              WebFigure myFigure = 
                 (WebFigure)((MWJavaObjectRef)results[0]).get();
       }
       finally
       {
              //Deployed Components use MWArrays which utilize 
              // Native Resources.
              //The Java Garbage collector can not properly 
              // clean up this memory so it is important to 
              // dispose these resources.
              MWArray.disposeArray(results);
       }
}
catch(ClassCastException e)
{
       throw new Exception
              ("WebFigure object was not 
                    of Type WebFigure.", e);
}

Back to Top

Attaching a WebFigure

All components access available WebFigures is by using Web server cache mechanisms. This allows you to leverage built-in J2EE mechanisms to scale your servers into a farm and automatically propagate the session across the servers.

There are a number of ways to attach a WebFigure to a scope, depending on the state:

• Attaching to the session cache session

• Attaching to the application cache application

Attaching to the Session Cache

This cache is visible only to the current user in a system and is usually used to store user session-specific information.

Attaching to the session cache can be an ideal choice if the figure is valid only for a specific user, at a certain time. To do this, add the following line of code to a JSP scriptlet or a servlet:

//from a JSP scriplet or a servlet to the Session cache
request.getSession().setAttribute("myFigure", myFigure);

If you manually attached the figure, but want the JSP tag to reference it, you can add the tag attributes:

name="myFigure" scope="session"

Note   The name given to the JSP tag must match the one used to attach it to a cache, and the name must be unique within that cache.

Attaching to the Application Cache

This cache is visible by all sessions in the current application. Attach to the application cache if you want to attach the figure globally for every page and servlet to use.

To attach to the Application scope, add the following line of code to a JSP scriptlet or a servlet:

//from a JSP scriplet or a servlet to the Application cache
request.getSession().getServletContext().setAttribute("GlobalFigure",
   myFigure);

If you manually attached the figure, but want the JSP tag to reference it, you can add the tag attributes:

name="GlobalFigure" scope="application"

Note   The name given to the JSP tag must match the one used to attach it to a cache, and the name must be unique within that cache.

Back to Top

Using the WebFigure JSP Tag to Reference a WebFigure

Once the WebFigure has been retrieved from the function output (see Getting the WebFigure Object from Your Method), you can attach it to one of your server's caches and reference it from the JSP tag.

Initializing the JSP Tag

Reference the tag library by adding the following line to a JSP page:

<%@ taglib 
   prefix="wf" 
   uri="http://www.mathworks.com/builderja/webfigures.tld" 
%>

Note   This code references the .tld file from the WEB-INF folder under your web application folder. This URI must be typed exactly as shown above for the name to properly resolve the reference. Once this tag has been referenced, you can add tags to the page similar to this: <wf:web-figure />

Note   If you use an empty tag as shown above, the default WebFigure appears. To bind the tag to your WebFigure, see Attaching a WebFigure.

Attributes of a WebFigure Tag

The key attributes for the WebFigure tag are name and scope. For each tag, use these parameters to indicate which figure to use in which cache on your server. Assuming you have attached a figure to the session cache using the string MyFigure (as shown in the Attaching a WebFigure), the JSP tag resembles this:

 <wf:web-figure name="MyFigure" scope="session"/>

Use this table to reference the following WebFigure tag attributes.

WebFigure Tag Attributes and Their Default Values

Attribute Name	Description	Optional?	Default Value
name	Name used when attaching your figure to a cache. Case sensitive.	Yes	The name of the default WebFigure built into WebFigureService. If you provide an empty WebFigure tag, this figure is displayed.
scope	Scope that your figure has been saved to (either application or session).	Yes	If this is not specified, an error is thrown unless the name is also not specified. In this case, the default figure is attached to the session scope and is used.
style	Style attribute that you want embedded and attached to the iFrame.	Yes	If this is not passed, a basic iFrame is used.
height	Height of the iFrame that will be embedded.	Yes	If this is not passed, the height of the WebFigure is retrieved from cache.
width	Width of the iFrame that will be embedded.	Yes	If this is not passed, the width of the WebFigure is retrieved from cache.
root	Name used to map the WebFiguresServlet for a figure.	Yes	If this is not specified, it is assumed to be mapped to WebFigures. If it is specified to a relative servlet end point, that is used.

Back to Top

Getting an Embeddable String That References a WebFigure Attached to a Cache

If you do not want to use the WebFigure JSP tag to display the figure, or want a servlet to display it directly, use this method to get a snippet of HTML that will embed an iFrame containing the figure in another page.

1. Create an instance of the WebFigureHtmlGenerator class using either a scriptlet or a servlet. The constructor for this class has three overloads:

   //The import statement needed to invoke this class
   import com.mathworks.toolbox.javabuilder.webfigures.WebFigureHtmlGenerator;
   
   
   //WebFigureHtmlGenerator(HttpServletRequest servletRequest)
   //This overload just takes the ServletRequest and will map the 
   //  embed string to the same server and assumes that the 
   //  WebFiguresService was mapped to "WebFigures"
   WebFigureHtmlGenerator htmlGenerator = 
   			WebFigureHtmlGenerator(servletRequest);
   
   //OR
   
   //WebFigureHtmlGenerator(String webFigureServletNameMapping, HttpServletRequest 
   //     servletRequest)
   //This overload takes the ServletRequest and the name that 
   //  the WebFigureServlet was mapped to.  
   //It will reference this servlet on the same server 
   WebFigureHtmlGenerator htmlGenerator = 
   			WebFigureHtmlGenerator("SomeServletMappingName", servletRequest);
   
   //OR
   
   //WebFigureHtmlGenerator(String absolutePathName)
   //This overload takes the absolute URL path to a server that has 
   // WebFiguresService running.
   //This would be used if you have a cluster of servers that are all running 
   // WebFigureService 
   // a load balancer (all sharing cache state). Use 
   // this parameter to reference that base load balancer URL.
   WebFigureHtmlGenerator htmlGenerator = 
   			WebFigureHtmlGenerator("http://someLoadBalancer/someWebApplication/
                                                 WebFigureServletNameMapping");
   

2. Call the method to get the embedded string (getFigureEmbedString). Use this table to specify appropriate attributes:

   Attribute Name	Attribute Type	Description	Optional	Default Value
   figure	WebFigure	WebFigure for which you want to create the embedded string.	Yes	This is used to determine the figure's default height and width if no other is provided .
   name	String	Name used when attaching your figure to a cache. Case sensitive.	No	Not optional
   scope	String	Scope that figure has been saved to (application or session).	No	Not optional
   style	String	Embedded attribute you want attached to the iFrame.	Yes	If this is not passed, a basic iFrame is used.
   height	String	Height of the iFrame that will be embedded.	Yes	If this is not passed, the height of the WebFigure is retrieved from cache. If the WebFigure cannot be found, the MATLAB default height for a figure (420) is used.
   width	String	Width of the iFrame that will be embedded.	Yes	If this is not passed, the width of the WebFigure is retrieved from cache. If the WebFigure cannot be found, the MATLAB default width for a figure (560) is used.

Back to Top

Quick Start: Implementing a Custom WebFigure

Working with MATLAB Figures and Images

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS