Creating a CATlet

3D PLM Enterprise Architecture	Webtop	Creating a CATlet Creating a new CATlet (the MVC Structure) in the Portal
Use Case

Abstract

This article shows how to create a CATlet and so presents the interaction between the Model, View and Controller.

What You Will Learn With This Use Case
The FoodStoreCATlet Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show how to create a CATlet and so presents the interaction between the Model, the View and the Controller, which create the CATlet bean.

A CATlet can be assimilated to a Java Bean but it is a more than a Java Bean in the way it is designed to fit inside the Portal and as such has built-in functionalities to enhance this integration . Be careful: as a standard Java Bean a CATlet can be instantiated anywhere outside the Portal and any Java Bean can be instantiated inside the Portal (but with a degraded integration). A CATlet is a graphical container and is built around the model-view-controller paradigm (named MVC). The CATlet is itself the controller of the whole component and aggregates its views and models. A CATlet can have many views and models but most of the time it has only one for each. In the Portal, a CATlet can be added in the WebInfo part, as a browser CATlet or can be added in the WebSpace part, as a viewer CATlet.

[Top]

The FoodStoreCATlet Use Case

The FoodStoreCATlet is a use case of the CAAJApplicationFrame.edu framework that illustrates the creation of a new CATlet and its integration in the Portal.
It uses the JCATlet, swing implementation of the ICATlet interface from the JApplicationFrame framework, the ViewInterface interface and the Model class from the PortalBase framework.

[Top]

What Does FoodStoreCATlet Do

The FoodStoreCATlet use case creates a food store where end users can select food items in different food categories. This use case creates a FoodStoreModel (the Model) which contains the stock of the store, a FoodStoreView (the View) which displays the food store content, and a FoodStoreCATlet (the Controller) which manages the view and the model of this store.

Be careful that we use the term CATlet to represent two things: the whole component (Model View and Controller) as well as the controller itself. This may be confusing but in fact they represent quite the same thing: The CATlet is the graphical controller component added inside the Portal and it is the only part of the MVC, visible from outside.
All the intelligence of the MVC component is located in the CATlet (the Controller). The Model is meant to store the data of this component and the View to display all or part of these data.

The FoodStoreCATlet is the controller of the MVC application and plays the following roles:

It is the graphical component added to the Portal ( FoodStoreCATlet extends the JCATlet swing graphic component)
It creates theFoodStoreModel (which extends the Model class) and the FoodStoreView (a graphical component which implements the ViewInterface)
It manages the View and the Model by direct method (it has a reference on them).
It subscribes the View to property events from the Model and subscribes itself to events from the view.

[Top]

How to Launch FoodStoreCATlet

To launch the FoodStoreCATlet, you will need to set up the build time environment, then compile FoodStoreCATlet along with its prerequisites, set up the run time environment, and then execute the use case [1].

Specify the FilePrefix CAAGw0 in the Portal launching command, logon to the Portal and do the following steps:

Select the CATlet list Workbook. (If you already have a personal Workbook list customization and the CATlet list Workbook does not appear, then customize your personal Workbook list and add the CATlet list Workbook)
In the WebInfo part, double click on the FoodStore CATlet item which will add the CATlet in the WebSpace part.

[Top]

Where to Find the FoodStoreCATlet Code

The FoodStoreCATlet use case is one part of an entire use case scenario. It is made of 3 main classes named FoodStoreCATlet , FoodStoreModel and FoodStoreView located in the CAAGw0FoodStore.mj module of the CAAJApplicationFrame.edu framework:

Windows	`InstallRootDirectory\CAAJApplicationFrame.edu\CAAGw0FoodStore.mj\`
Unix	`InstallRootDirectory/CAAJApplicationFrame.edu/CAAGw0FoodStore.mj/`

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

Top]

Step-by-Step

To create the FoodStoreCATlet MVC, there are five steps:

#	Step	Where
1	Create the Model class file	FoodStoreModel.java
2	Create the View class file	FoodStoreView.java
3	Create the CATlet class file	FoodStoreCATlet.java
4	Create the CATletBeanInfo class file	FoodStoreCATletBeanInfo.java
5	Declare CATlet in the CATlet list configuration file	CAAGw0CATletList.xml

[Top]

Creating the Model Class

The models of a CATlet extend the Model class. A CATlet can have several models, but more often it has only one Model.
The FoodStoreCATlet use case has only one model, the FoodStoreModel. It is defined as follows:

package com.dassault_systemes.japplicationframe.caa.catlet.model;
...
public class FoodStoreModel extends Model
{
public FoodStoreModel()
  {
   // --- initialize data contained
   ...
  }
 ...
 /**
  * set the list of FoodItem for the current food category  
  */
 public void setCurrentFoodItems(FoodItem[] foodItems)
  {
   if(foodItems != null)
    {
     FoodItem[] oldFoodItems = currentFoodItems;
     currentFoodItems = foodItems;

     // --- fire a PropertyChangeEvent (to the View) with the new current food items
     support.firePropertyChange("Current Food Items", oldFoodItems, currentFoodItems);
    }
  }
  ...
}

FoodStoreModel derives from Model. It inherits the PropertyChangeEvent management from the Model class, and so can fire event to the view by called the PropertyChangeSupport support.

[Top]

Creating the View Class

The views of CATlet implement the ViewInterface interface and extend graphical components (Swing graphic components in this use case because the FoodStoreCATlet extends the swing implementation of the ICATlet) . A CATlet can have several views, but more often it has only onel.
The FoodStoreView is defined as follows:

package com.dassault_systemes.japplicationframe.caa.catlet.view;
...
public class FoodStoreView extends JPanel
                           implements ViewInterface
                                     ,ActionListener
				     ,ListSelectionListener
{
  public FoodStoreView()
  {
    // --- create graphical view components layout
    ...
}

 public Component getGUI()
  {
    return this;
  }
  public void propertyChange(PropertyChangeEvent evt)
  {
    // --- listen PropertyChangeEvent from the FoodStoreModel and update the view
    ...
  }
  public void addFoodListener(FoodListener l)
  {
    foodListeners.addElement(l);
  }
   
 public void removeFoodListener(FoodListener l)
  {
    foodListeners.removeElement(l);
  }
   
 public void fireFoodEvent(FoodEvent evt)
  {
    // --- fire foodEvent to all FoodListener registered (FoodStoreCATlet)
    ...
  }
 ...
}

FoodStoreView derives from a Swing graphic component (JPanel) and implements the ViewInterface. The events subscription in the MVC are made by the CATlet, which is the only one component to know each part of the MVC. The CATlet subscribes the View to the PropertyChangeEvents from the Model, and subscribes itself to the events from the View.

The View listens to the PropertyChangeEvent from the FoodStoreModel, in order to update the view of the store with the new data of the model. It fires FoodEvents to the FoodStoreCATlet in order to inform the controller of end user interactions and selection of data views.

Top]

Creating the CATlet class

The FoodStoreCATlet is as follows:

package com.dassault_systemes.japplicationframe.caa.catlet;
...
public class FoodStoreCATlet extends JCATlet
                             implements FoodListener
				       ,PortalURLHandler
{

 public FoodStoreCATlet()
  {
    // --- create the view for this CATlet
    views = new ViewInterface[1];
    views[0] = new FoodStoreView();
    
    // --- create the model for this CATlet
    models = new Model[1];
    models[0] = new FoodStoreModel();
    
    // --- make the view subscribe to PropertyChangeEvents from the model
    models[0].addPropertyChangeListener(views[0]);
    
    // --- subscribe to FoodEvents from the view
    ((FoodStoreView)views[0]).addFoodListener(this);
    
    // --- add the view GUI inside the CATlet
    add(views[0].getGUI());
    
    // --- initialize the model
    ((FoodStoreModel)models[0]).initializeModel();
  }
  public void cleanup()
  {
    // --- make the view unsubscribe to PropertyChangeEvents from the model
    models[0].removePropertyChangeListener(views[0]);
    
    // --- unsubscribe to FoodEvents from the view
    ((FoodStoreView)views[0]).removeFoodListener(this);
    
    // --- cleanup internal reference on objects for the Garbage Collector
    ...
  }
   
 public void activate()
  {
    ...
  }

 public void deactivate()
  {
    ...
  }

 public void foodCategorySelected(FoodEvent evt)
  {
    // --- Implementation of FoodListener for FoodCategory selection from FoodStoreView
    ...
  }
     
 public void foodItemSelected(FoodEvent evt)
  {
    // --- Implementation of FoodListener for FoodCategory selection from FoodStoreView
    ...
  }
  ...
}

FoodStoreCATlet derives from JCATlet (the Swing implementation of the ICATlet interface). For AWT implementation of the ICATlet interface extend the CATlet class of the PortalBase framework. The FoodStoreCATlet implements the abstract methods cleanup(), activate(), and deactivate() of the JCATlet. It implements the FoodListener interface in order to listen to the end user interactions.

The FoodStoreCATlet constructor:

Initializes the ViewInterface and the Model arrays.
Creates the view and the model of the CATlet.
Subscribes the view to PropertyChangeEvent from the model
Dubscribes itself to events from the view (FoodEvent in this case)
Adds the View graphical user interface to the CATlet
Initializes the model.

The CATlet methods called by the Portal desktop during the CATlet lifecycle:

The end user asks the CATlet creation : The Portal dekstop calls the CATlet constructor, adds the CATlet in the desktop and calls it on the activate() method.
The end user switches on a second CATlet : The Portal desktop calls the first on deactivate() method and calls the second one on activate() method.
The end user closes the CATlet: The Portal desktop calls the CATlet on deactivate() method, removes it of the frame, calls it on cleanup() method and forgets all references on it.

[Top]

Creating the CATletBeanInfo class

The FoodStoreCATletBeanInfo describes the bean FoodStoreCATlet as follows:

package com.dassault_systemes.japplicationframe.caa.catlet;
...
public class FoodStoreCATletBeanInfo extends CATletBeanInfo
{
  ...
  protected EventSetDescriptor[] getPublishedEventDescriptors()
  {
    // --- Construct the list of EventSetDescriptor which represent the events published by the CATlet bean
    ...
  }

 public PropertyDescriptor[] getPropertyDescriptors()
  {
    // --- Construct the list of PropertyDescriptor which represent the property exposed by the CATlet bean
    ...
  }

 public Image getIcon(int iconKind)
  {
    if(iconKind == ICON_COLOR_32x32)
	return ImageLoader.loadImagefromClassRoot("Resources/I_Wk13.gif");
    else return super.getIcon(iconKind);
  }

 public BeanDescriptor getBeanDescriptor()
  {
   BeanDescriptor desc = super.getBeanDescriptor();
   desc.setDisplayName(FoodStoreLanguage.getWidgetsString("FoodStoreCATlet"));

   return desc;
  }
}

FoodStoreCATletBeanInfo derives from CATletBeanInfo. It overrides the getIcon() and getBeanDescriptor() methods of the CATletBeanInfo, in order to specify its icon representation and its NLS display name for the end user.

The two methods getPublishedEventDescriptors() and getPropertyDescriptors() are used by the bean introspection. The property descriptor is used in the Portal by the PortalURL and the PropertyCATletCustomizer command. The Published EventDescriptor is used in the Portal by the Hookup for the event publishers declaration.

[Top]

Declaring CATlet in the CATlet list configuration file

For the CAAJApplicationFrame application, a new CATletList file is created with the FilePrefix CAAGw0. The CAAGw0CATletList.xml is as follow

<?xml version="1.0" encoding="UTF-8"?>
<CATletList>
	<BrowserCATlets>
		<CATlet icon="Resources/I_CATlet.gif" 
                        label="CATlets List" 
                        label.fr="Liste des CATlets"
                        label.en="CATlets List" 
                        label.de="CATlets List" 
                        label.ja=""CATlets List" 
                        help="/help/english/ptlug/ptlugbt0700.htm"
                        help.fr="/help/french/ptlug/ptlugbt0700.htm"
                        help.en="/help/english/ptlug/ptlugbt0700.htm"
                        help.de="/help/german/ptlug/ptlugbt0700.htm"
                        help.ja="/help/japanese/ptlug/ptlugbt0700.htm"
                        multiThread="false"
                        url="bean://com.dassault_systemes.catweb.frame.catlet.ViewerListCATlet">
		</CATlet>
		...

	</BrowserCATlets>

	<ViewerCATlets>
		<CATlet icon="Resources/I_Wk13.gif" 
                        label="Food store" 
                        label.fr="Alimentation"
                        label.en="Food store" 
                        label.de="Food store"
                        label.ja="Food store" 
                        help=""
                        help.fr=""
                        help.en=""
                        help.de=""
                        help.ja=""
			workshop="FoodStoreCATlet.workshop"
                        url="bean://com.dassault_systemes.japplicationframe.caa.catlet.FoodStoreCATlet">
		</CATlet>

		...		

	</ViewerCATlets>

	<OtherCATlets>

		...		
	</OtherCATlets>
</CATletList>

The CAAGw0CATletList.xml contains the declaration of the CAA use case CATlet used by the Portal and so contains the FoodStoreCATlet declaration.

There are three kinds of CATlet declarations:

The BrowserCATlets are displayed in the WebInfo part associated with a Workbook icon.
The ViewerCATlets are displayed in the WebSpace part and can be activated by a BrowserCATlets or a document selection (with MIME Type registry).
The OtherCATlets are displayed in the WebSpace part and cannot be directly activated by document selection, and are not listed in the CATlet List.

In this use case the FoodStoreCATlet is displayed in the WebSpace part. It is activated when the end user selects its icon in the CATlet list, or when the user activates a ".stock" document.

[Top]

In Short

The use case show what is a CATlet and how to create one. The CATlet is a graphical container and is built around the model-view-controller paradigm (named MVC). The CATlet is itself the controller of the whole component and aggregates its views (which implement the ViewInterface interface) and models (which extends the Model class). A CATlet need to implement the ICATlet interface. Two default basic implementation are delivered : The AWT implementation named CATlet and delivered in the PortalBase framework,. The Swing implementation named JCATlet and delivered in the JApplicationFrame framework.

[Top]

References

[1]	Building and Launching a CAA Enovia V5 Use Case
[Top]

History

Version: 1 [Sep 2000]	Document created
[Top]

3D PLM Enterprise Architecture

Webtop