Understanding FPM application for WDJ platform

[Former Member]

Applies to: SAP NetWeaver Enterprise Portal 7.0, WebDynpro for Java.

Summary:  The document basically describes the concept and working of Floor plan manager for Web Dynpro Java platform. After going through this article you will be able to understand the basics of FPM.

Preconditions

The following are the preconditions that we need.

• Basic Concepts of Java programming.
• Basic knowledge in SAP EP 7.0.
• An overview of Web Dynpro Programming

Web Dynpro:

Web Dynpro is a client-independent programming model of the SAP NetWeaver technology platform for developing user interfaces for professional business applications. It is based on the model view controller paradigm which ensures that the business logic is separated from the presentation logic. This architecture is visible in the Web Dynpro perspective of the SAP NetWeaver Developer Studio (NWDS).

Floor Plan Manager:

The Floor Plan Manager (FPM) is a framework for developing self-service applications using Web Dynpro for Java.

The Floor Plan Manager insures that all self-service applications follow a consistent pattern or road map. The pattern itself was designed to make the applications easily recognizable, clearly structured and simple to use. As a result, once you have set up the self-service applications for your enterprise, there is minimal requirement for end-user training.

Overview of application component in WDJ: Each part of the diagram is explained in detail below.

Components of self-service application:  Besides the visual elements, a self-service application needs at least two invisible elements.

• Visual Application Component (VAC) implements IVAC interface

VACs are the building blocks of perspectives. They display data on the screen, handle user input, and trigger FPM events.

• Business Logic Component (BLC) implements IBLC interface

BLCs are invisible components that handle communication between the application and the backend system. They use one or more Web Dynpro models and prepare the frontend data to be sent to the backend and the backend data for to be displayed in a VAC.

• Configuration Component (CC) implements IXssAppConf interface

CCs are components that define the perspectives and navigation paths of the self-service application. The FPM obtains the layout of a perspective from the CC of the application and uses this information to build the perspectives. In step Initialize new VACs/BLCs step, the FPM calls the CC to determine the layout of the next perspective.

Now we are familiar with the concept of components of self-service application, let us go into details of FPM.

Self-Services User Interface Pattern:

Two patterns, however, are part of nearly every self-service application:

• The Roadmap Pattern (ROP)
• The Context Assistance Pattern (CAP)

These patterns ensure that the application offers user guidance and context-sensitive assistance to the user.

• The Roadmap Pattern (ROP):   The standard implementation of the Roadmap Pattern consists of the Roadmap control on top of the screen and a row of navigation buttons at the bottom.

              

• The Context Assistance Pattern (CAP): This is another widely-used pattern in self-service applications. The purpose of this pattern is to offer context-related information to the user.

The visual realization of a Context Assistance Pattern is a list of ‘link-style’ text labels, which in fact are small UI controls that open or close the corresponding screen area. In the diagram below, the view area ‘Time Accounts’ is currently open. By clicking the label ‘Time Accounts’ once more, the CAP would be minimized and only the list of labels remains visible.

          

Elements of a Self-Service Application:

Each self-service application is a unique type of Web Dynpro application. Each application is part of a development component (DC) and uses components, component interfaces, and models as building blocks. The application itself is defined by its starting point, that is, which window of which component is to be displayed first. Once the first window of the application is visible, the behavior of the application depends on events initiated by the user and the system’s responses.

The windows of Web Dynpro Components are composed of multiple assembled views. An application following the self-service pattern needs several such views – namely, one for each (possible) step of the floor plan. For minor applications, this requirement would demand a great deal of effort simply for the navigation. Fortunately, the FPM substantially reduces this effort.

A self-service application uses assembled views called perspectives. A perspective defines the visual content of an application in a certain state – that is, which visual elements are contained in a particular screen. The complete user interface of a self-service application is defined by the perspectives it contains and by the possible navigation paths between these perspectives. Often, a one-to-one relationship exists between perspectives and roadmap steps.

Component Interfaces: To enable communication between the FPM and the components of the self-service application, the components must implement certain standard interfaces. Those interfaces are described below.

Interface IVAC:  This interface defines a visual application component (VAC). It is the only interface that not only defines a set of methods that the component interface must implement, but also creates an interface view in the component interface.

Consequently, your VAC automatically possesses a window named IVACWindow. All the visual parts of your VAC (usually one or more Web Dynpro views) are required to be included in this window. If this is not the case; otherwise they will not be visible.

Methods of this interface are illustrated below:

• public void onInit ( com.sap.pcuigp.xssfpm.java.IFPM fpm ) -> This method is called once for each VAC when it is initialized. For registering BLCs (Business Logic Components) in VAC this method can be utilized.
• public void onCleanup() -> This method is called once for each VAC when the application exits. This routine is used to remove unnecessary data and data locks from the VACs.
• public void onFlush() -> called at the beginning of an FPM event loop. This method has to be used to transport new or updated data to the BLC, but only when context mapping does not perform this action automatically. So if all the fields of a VAC are directly or indirectly mapped to BLC, their values are automatically updated. In this case, the onFlush routine need not be called by the FPM.
• public void onHide() -> It is called in an FPM event loop when a current perspective changes and a VAC is closed. Your VAC should be in a consistent state when this method is called.
• public void onBeforeOutput() -> This method is called in every FPM event loop when the perspective is built.
• public boolean onEvent() -> This method is called for every FPM event except for selection change events that users cancel, as well as the exit events.If the VAC cannot perform the event-specific operations so that the event can be processed correctly, it has to return false on this method to jump to the end of the current event loop. In this case, the next perspective corresponding to this event will not be built. The VAC usually raises a message to inform the user of the problem.
• public void onEventCompleted( boolean successful ) -> This method notifies your VAC about whether or not an event has been processed successfully. If one of the visible VACs of the perspective could not process the event correctly, the parameter successful of the method is false. If the event has been processed correctly, the value is true.
• public boolean isDirty() -> This method allows the VACs to return information about whether or not the data they contain has already been saved. The method prevents unintentional loss of data.
• public boolean isConsistent() -> This method is called on VACs that are to be hidden at the end of the event loop. This method allows the VACs to return information about whether or not the data they contain is consistent. This method prevents your application from collecting data on one perspective that cannot be processed in one of the subsequent perspectives.

          More information on these methods can be found on http://wiki.sdn.sap.com/wiki/display/WDJava/methods+in+FPM

Interface IBLC: Methods of this interface are illustrated below:

• public void onInit( com.sap.pcuigp.xssfpm.java.IFPM fpm) -> This method is called once for each BLC when it is initialized. During initialization, a BLC usually creates instances of the model classes that provide the connection to the backend system. After that, the initial call to the backend system is made to fill the context nodes of the BLC with the initial data.
• public void onCleanup() -> This method is called once for each BLC when the FPM Application is closed. This method is used to release locks in the backend system, free up system resources, or close open connections

Interface IXSSAppConf: Interface IXSSAppConfig must be implemented by the Configuration Components of a Self-Service Application. With the release of the Self-Services Framework in mySAP ERP 2005, it is possible to configure the application directly in the Enterprise Portal Content Directory. The application usesa generic CC and the application programmers do not have to write their own Configuration Component.Methods are as follows:

• public void loadConfiguration( com.sap.pcuigp.xssfpm.java.IFPM fpm) -> This method is called once for each Configuration Controller when it is initialized. This method is used to initialize the internal representation of the navigation graph, the appearance of the roadmap, and the content and behavior of the CAP.
• public Perspective getStartPerspective() -> after configuration component has been initialized. This method is used to set the default perspective for the application.
• public Perspective getNextPerspective( Perspective currentPerspective, String eventName ) -> This method is called at the end of the FPM event loop to determine the next perspective that has to be built. This method is used to implement the navigation graph of the application.
• public ROPState getROPState( Perspective perspective ) -> This method is called at the beginning of the FPM event loop to define the state of the roadmap on the current perspective.
• public CAPState getCAPState( Perspective perspective ) -> This method is called at the beginning of the FPM event loop to define the state of the Context Assistance Pattern on the current perspective.

The Floor Plan Manager Event Loop:

Web Dynpro applications are event-driven programs. The visual elements of the application — such as buttons, checkboxes and edit controls — communicate with one another by raising events and reacting to events received through the Web Dynpro framework.

This section focuses on the events that affect components other than the one that raised the event. These include:

• Various data selection events where another component (the BLC) has to get data from the backend.
• Navigation events where a perspective changes or is replaced by another perspective.
• User events where an action inside a VAC influences what can be seen in another VAC.

A typical example of a local event is seen when the main selection in one VAC is changed and the corresponding detail VAC is updated. These events are called framework events, or Floor Plan Manager Events. Instead of dealing with all the consequences of a framework event itself, the self-service application notifies the Floor Plan Manager about the event. This triggers the FPM event loop and makes the FPM perform the following tasks:

• Notify all VACs of the current perspective to perform certain checks or actions, depending on the nature of the framework event
• Hide VACs that are no longer required
• Initialize new VACs
• Build the next perspective or refresh the current perspective

Process flow (FPM event loop):

              

As indicated in the diagram, for some of the steps in the FPM event loop, a veto from the application is possible. In such cases, a VAC may notify the FPM that its current state does not permit the event loop to be performed. For example, if the application data from the VAC has been modified and no save event has been processed, the VAC method isDirty() would have to return the value true, indicating that unsaved data is present. If this is the case, the FPM interrupts the processing of the event loop and displays a warning that data might be lost.

Floor Plan Manager Events:

1. User Event: This event type triggers the event loop. It can be used for application-specific events that have to be communicated between the visible VACs of the current perspective. It can also be used to trigger a change of perspective.
2. Save Event: This event starts the event loop to save all modified or created objects and change to the System Confirmation perspective
3. Review-and-Save Event: This event must be triggered after the user has modified objects and wants to save the modified data
4. Selection Change Event: This event should be triggered whenever the main selection of the application — for example the selected request in the leave request application — changes. For a selection change event, the FPM checks every VAC to determine whether it has any unsaved data. If a VAC has data that has not been saved (‘dirty’ state), it raises a veto against the selection change and the FPM displays a warning message stating that data might be lost. In response, the user can decide to stop or resume the event loop. The sequence diagram of the Selection Change Event is depicted below.

              

     5. Exit Event: The FPM provides a method to end the self-service application regardless of whether or not data has been saved. This is not strictly an event type of the self-service framework. It is not used to process an application-specific event. Instead, it is used to stop the application and navigate away from it. (Should be used in Exit button and confirmation links). The FPM sends a message to the VACs and BLCs to allow them to perform a clean-up before they are closed. The sequence diagram of the Exit Event is depicted below.

              

              

FPM Views and FPM Applications:

FPM views are the Enterprise Portal objects that represent Visual Application Components (VAC). FPM applications are the Enterprise Portal objects that represent Self-Service Applications.

An FPM view has two main properties: the name of the development component and the name of the Web Dynpro component. Since an FPM view represents a VAC, meaning that the component implements interface IVAC, it is guaranteed that the window IVACWindow is present. The FPM uses this window to display the VAC on the screen.

  Below screenshot illustrates an FPM view where on creation we have to select a DC(Development Component) and further the Web Dynpro Component of that selected DC.

              

              

FPM views can raise events to trigger certain actions of the application. The perspectives aggregate the events of the Views they contain. By assigning FPM Views to Perspectives, these Perspectives can use the events raised by the assigned Views to navigate to another perspective. This connection is called an event link and it points to exactly one target perspective. Thus, each perspective contains a set of event links, ranging between zero and the number of all event definitions for all FPM views.

              

Below screenshot represents an FPM Application.First step is “Define Road Map”, in which we define road map steps like Overview,Edit etc. and whether the previous navigation from that step is possible or not by selecting the check box.

              

We specify the Development component and Web Dynpro Component in FPM view which will then be embedded into FPM application.

              

Then we go to the “Define Perspective” step and choose a road map step from drop-down. A perspective is created or deleted by clicking on the create/Delete button respectively below the perspective table.

              

Information and API Retrieval:

The last groups of IFPM methods are methods that are used to get something from the FPM.

public IMessageManager getMessageManager()

public EventData getEventData()

public IFPMInternals getInternals()

public ApplicationContext getApplicationContext()

public String getPropertyValue(String name)

Interface IMessageManager: Unlike the Web Dynpro message manager, all messages of the FPM message manager are persisted and shown on each screen of the application until they are explicitly deleted. The methods reportMessage()and raiseException()add messages to the FPM’s internal list of messages. Although the Web Dynpro for Java runtime environment is fully equipped with a message manager (interface IWDMessageManager), the FPM offers a message manager interface of its own.

The interface IMessageManager is a wrapper around the standard Web Dynpro message manager and serves to simplify the application.

public void	reportMessage( <various signatures> )
public void	raiseException(<various signatures> )
public void	deleteAllMessages()
public void	logAdminWarning()
public void	logAdminError()

Class EventData: The FPM uses objects of class EventData to store all the information about an event. Application programmers can access the event data of the currently processed event using the method getEventData() of the interface IFPM.

public String	getEventType()
public VAC	getRaisingVAC()
public BLC	getBLC()
public boolean	equals(Object obj)
public int	hashCode()
public string	getEventName()

Interface IFPMInternals: This method returns the perspective your application is currently displaying.   

public Perspective getCurrentPerspective()

Class ApplicationContext:

public java.util.Properties	getApplicationProperties()
public java.util.Properties	getRequestParameters()
public boolean	isDebugMode()
public boolean	isPortal()
public SessionData	getSessionData()
public boolean	isExitButtonAllowed()

Using the Floor Plan Manager:

  The Floor Plan Manager is embedded into the Web Dynpro component FPMComponent. To integrate the FPM into a self-service application, this component has to start the application. In other words, the application programmer builds components that are part of the application but every self-service application uses the same component and the same window of component FPMComponent as a starting point for executing the program.

              

The application launches the FPM on startup by specifying the FPMComponentWindow of the FPMComponent as the starting point. In return, the application receives a handle to the interface IFPM from the FPM. Using this interface, the application raises framework events and retrieves instances of the FPM utility classes if needed.

  Besides the component FPMComponent, the FPM development components comprise a number of generic BLCs. A self-service application may utilize these components by declaring them as Used Web Dynpro Components in their own components.

Interface IFPM

The IFPM interface grants the self-service applications access to the Floor Plan Manager and its utility classes. The components of the self-service application receive references to the IFPM on startup, as shown below:

• VACs and BLCs with method onInit(IFPM fpm)
• CCs with method loadConfiguration(IFPM fpm)

1. Backend Connection Handling -> in BLC

The interface IFPM features two methods for setting up the backend connection via the JCO adapter, one of them with two signatures.

public void	connectModel(DynamicRFCModel model)
public void	connectModel(DynamicRFCModel model, String rollAreaKey)
public void	disconnectModel(DynamicRFCModel model)

When your application exits, you have to use the method disconnectModel() to cleanup your existing connection(s). The standard places for connecting and disconnecting your models are the methods onInit() and onCleanup() of your BLCs.

   2. Event Handling and Navigation -> in VAC

The methods that fall into this group invoke the FPM’s event loop and perform a number of call-backs to the VACs of the application.

public void	raiseEvent(String eventName, VAC raising VAC)
public void	voidraiseSelectionChangeEvent(String eventName, VAC raising VAC)
public void	raiseSaveEvent(String eventName, VAC raising VAC)
public void	raiseReviewAndSaveEvent(String eventNameReview, String eventNameSave, VAC raising VAC)
public void	navigate(NavigationTarget navigationTarget)
public void	exitCalled()

More details of these methods and interfaces can be found on http://help.sap.com

The VACs of the application invoke these methods when they react to user input. The execution of the event loop that follows these method calls is explained in Event Loop Variations. Here is an overview of the parameters used.

eventName, eventNameReview, eventNameSave: These are names of events used to define the application’s navigation paths in the configuration component. Usually this is one of the predefined event names of the FPM (see table below).

raisingVAC: This parameter of class type VAC identifies the VAC that raises the FPM event.

navigationTarget: This parameter of class NavigationTarget specifies the Web page or Web application that is to be displayed next. You can both use the constructor of class NavigationTarget directly and specify an arbitrary URL as the target (see section Class NavigationTarget), or you can use the utility component FcNavigation of the FPM to obtain one of the logical navigation targets of the self-services framework (see section Component FcNavigation).

Registration of BLC Usage: The Web Dynpro Java framework contains several possibilities for declaring the usage of other components. Most prominent among them is the declaration of required controllers in the properties of a Web Dynpro component. Before a component has access to the component interface of another component, it must first define the used component in this list.

Unfortunately, the FPM cannot automatically ascertain which BLCs are used by a VAC. Therefore, the VAC must explicitly declare the component usage of the associated BLC. This is done by calling the following method:

public void attachComponentToUsage (IWDComponent component, IWDComponentUsage usage)

The BLC registration has to be used whenever a VAC uses methods of a BLC. Unfortunately, the registration is not enough to ensure that the BLC is initialized correctly. Since in a default component usage the Web Dynpro runtime takes care of the instantiation of components, we have to override this behavior by setting the component lifecycle to ‘manual’.

The lifetime of Web Dynpro Component Usages of components attached to the FPM is always manual.

Registration for Context Debugging: The Web Dynpro component context is a powerful and elegant tool for storing and distributing persistent data in a Web Dynpro application. There is, however, one constraint when you want to debug, in that it can be problematic to determine the actual content of a certain context node or attribute.

To remedy this, the FPM includes a tool for visualizing the context of a VAC or BLC. To register the context of a certain component for the FPM, use the method:

public void registerContext(IWDNode context)

  In the method onInit() of your component. After you have registered your context, the context display is activated using the URL parameter sap.xss.debug=yes when you start your application. Each registered context appears as a tree control below the application perspectives.

Utility Components: Similarly to other Web Dynpro development components, the FPM contains numerous components. There are a number of BLCs that are intended for general use within self-service applications. This section describes these generic BLCs.

Component FcNavigation: This component is a kind of factory class for instances of class NavigationTarget. It frees the application programmer from the task of having to construct certain navigation targets. The class offers access to a number of generic navigation targets.

Component FcEmployeeServices: This component is used by Employee Self-Services to obtain basic information about the current user of the application.

  This component publishes the methods:

• public java.lang.String getEmployeenumber() ->  This method returns the personnel number (PERNR) of the current user
• public java.lang.String getCountrygrouping() ->This method returns the country grouping (MOLGA) of the current user.

Component VcLinks: This VAC is used to automatically render the links on the confirmation screen of the application. The component has the following methods:

• public voidaddActionLink(IWDAction action, String actionText) -> This method adds a link for an application defined action.
• public booleansetLinkParameter(String serviceKey, java.util.Properties parameter) -> This method adds a URL parameter or change an already-defined URL parameter.
• public void setLinkText(String serviceKey, String linkText ) ->This method changes the link text for a service.
• public voidsetUniversalParameter(java.util.Properties parameter) ->This method adds a common URL parameter to all links.

Navigation Graph: One variable of type NavigationGraph stores the navigation graph of the application and one variable of type HashMap (Java standard class) stores a list of all known perspectives.

  With the member variables of the configuration component defined, implement the method loadConfiguration() , which runs on startup of the application. The method performs the following actions:

• Initializes member variables (especially the VACs and the perspectives)
• Defines the navigation graph
• Creates a list of all perspectives

After defining the navigation graph, implement the two methods getStartPerspective() and getNextPerspective(). The purpose of these methods is to check the navigation graph of the application and return the required perspective to the FPM.

getROPState(): The FPM uses this method to build the roadmap for every perspective of the application.

In the onCancel() method of the interface controller, you need the FPM utility component FcNavigation to generate navigation targets.

Defining the Model: A model contains additional metadata that describes the actual connection to the backend system.Web Dynpro applications use models to communicate with a backend system. A model is a set of Java classes corresponding to one (or more) RFC-enabled function module(s) and its (or their) parameters.

Example of an FPM Application:

              

               

Related Content:

http://help.sap.com/