ZSAB_BAPI_EXPLORER function group contains all the function modules called via SAP Jco. These modules make use of existing SAP functions, further processing the data where needed:

• ZGET_BAPI_DOCS – responsible for getting bo/bapi documentation based on object type and method name. Calls existing BAPI_INTERFACE_GETDOCU function.
• ZGET_BAPI_INFO – responsible for getting full bapi info. Calls existing SWO_QUERY_METHOD function.
• ZGET_BO_INFO – responsible for getting full bo info. Calls existing SWO_QUERY_BASEDATA function.
• ZGET_BO_LIST – responsible for getting a table with all objects name and type. Calls existing BAPI_MONITOR_GETLIST function.
• ZGET_BO_METHODS – responsible for getting a table with all object methods. Calls existing SWO_QUERY_API_METHODS function.

Here’s an example of such annotations for the GetBAPIList class, responsible for returning available methods for a given business object.

@ParentPackage("json-default")
@Action("get-bapi-list")
@Results({
    @Result(name="success", type="json"),
    @Result(name="error", location="error.jsp")
})
public class GetBAPIList extends ActionSupport {...}

The action parent package is defined as json-default, a package containing the json interceptor converting all bean properties to json format automatically. The url mapping for this class is defined as get-bapi-list. The most important feature in this example is the ability to define multiple results for the same action. A json string is returned on success and html content rendered via error.jsp is returned on error. This is not possible with standard struts2 annotations, can only be done via struts.xml configuration file which can dramatically grow in size as the application gets larger and more struts2 actions are defined and configured.

JSON plugin.
With the help of this plugin all action class bean properties are serialized into json format. Something really useful when communicating with the front-end via javascript ajax calls. To have the json interceptor activated for a given action, two elements are required:

• the action needs to be in a package containing the json interceptor – most probably the json-default package.
• the action needs to define the returned content type as json like in the above annotation example.

SAP Java Connector 3
There are two util classes used by all action classes to call abap remote functions:

• SAPDestinationDataProvider implementing DestinationDataProvider holds all info regarding abap stack and login credentials.
• SAPConnection initializes the JCo environment by registering the SAPDestinationDataProvider via com.sap.conn.jco.ext.Environment.registerDestinationDataProvider. Also responsible for returning JCoFunction instances for abap remote functions based on the abap function string name.

A typical call looks something like (code from GetBAPIInfo action class):

try {
   function = SAPConnection.getFunction("ZGET_BAPI_INFO");
   function.getImportParameterList().setValue("IM_BO_TYPE", objType);
   function.getImportParameterList().
   setValue("IM_METHOD_NAME", methodName);
   function.execute(SAPConnection.dConfig);

   structure = function.getExportParameterList().
   getStructure("EX_BAPI_INFO");
}
catch (JCoException e) {
   addActionError("JCo Error: " + e.getMessage() );
   return ERROR;
}

A JCoFunction reference to the corresponding abap remote function is acquired via custom SAPConnection util class. The function gets executed after setting the import parameters. Export parameters hold the function result and can be read via getStructure, getTable, etc..

In the above case, individual properties from EX_BAPI_INFO are accessed by structure.getString(”property_name”) such as structure.getString(”OBJTYPE”).

Example of the json format used:

{
   "objType":"BUS4003",
   "treeData":[
      {
            "state":null,"data":"FindDetail",
            "attributes":{"method":"FindDetail","type":"BUS4003"}
      },
      {
            "state":null,"data":"SaveReplica",
            "attributes":{"method":"SaveReplica","type":"BUS4003"}
      },
      {
            "state":null,"data":"Update",
            "attributes":{"method":"Update","type":"BUS4003"}
      }
   ]
}

data property is used by jsTree to render text for the current node. state property makes the difference between leaf and non-leaf nodes. attributes properties represent whatever custom data a node holds, in our case business object identified by object type and corresponding bapi identified by method name.

Besides providing the interaction for browsing/selecting business objects and their corresponding bapis, jsTree has another role: it dynamically updates the urls for the Detail and Documentation tabs from UI Tabs. It also reloads the current selected tab with the corresponding new url.

UI Tabs
Contains the Detail and Documentation tabs. Content is loaded via ajax under html format represented by several jsp pages: bapi_info.jsp, bo_info.jsp, generic_docs.jsp. The urls for these two tabs constantly changed based on current bo/bapi selection from jsTree.

The Detail tabs also serves as a place for displaying run-time errors like not being able to connect to the given abap stack.

Application similar to SAP BAPI transaction, showing various info about existing business objects and their methods (bapis). The end result is an ajax based html front-end capable of displaying the business object repository from an abap stack via java servlets.

jQuery Front-end
Everything happens in one main html page loading all bapi related content via ajax calls. The bapi tree component gets its data in json format, the detail and documentation sections get their data in html format. jQuery javascript library is being used extensively for both rendering various html elements and ajax data parsing.
More details

Struts2 Framework with SAP JCo3
Struts2 is being used as the application framework with a series of plugins like the convention and json plugin. Servlets get data from the ABAP stack via SAP Java Connector and return to front-end either json or html content. Front-end makes requests via GET parameters.
More details

ABAP Remote Function Modules
Custom dictionary structures and remote function calls for getting bapi related data.
More details

Source code: java , abap. Java archive contains both the src files and the deployed webapps directory without struts2 and jco external libraries. ABAP archive contains an SAP transport request with corresponding dictionary structures and function modules.

build.properties
Defines build properties used by build.xml including paths for flex sdk, flex compilers, external modules and libraries. FLEX_HOME stands out from the low-case naming convention and is required by all flex ant tasks:

flex.sdk = C:/flex_sdks/3.4.1
FLEX_HOME = ${flex.sdk}
flex.framework = ${flex.sdk}/frameworks/libs

flex.mxmlc = ${flex.sdk}/bin/mxmlc.exe
flex.compc = ${flex.sdk}/bin/compc.exe
flex.asdoc = ${flex.sdk}/bin/asdoc.exe
flex.optimizer = ${flex.sdk}/bin/optimizer.exe
flex.digest = ${flex.sdk}/bin/digest.exe

project.dir = ${basedir}/..
...

asabau_cg3_fb_config.xml
Contains additional compiler options when using mxmlc or compc flex ant tasks. Used for specifying metadata tags required by the Parsley framework that if not listed here won’t make it into the compiled swf/swc file. Extract from this file:

<keep-as3-metadata>
	...
	<name>Metadata</name>
	<name>AsyncInit</name>
	<name>ManagedEvents</name>
	<name>Command</name>
	<name>CommandResult</name>
	<name>CommandError</name>
	<name>CommandStatus</name>
	...
</keep-as3-metadata>

build.xml
Main build file. Contains tasks for compiling each external module and library, as well as a compile_main_launcher task putting it all together:

<target
  name="compile_main_launcher"
  depends="init, compile_api, copyRSLs"
  >
  <compile_module
    input.file="${asabau_cg3_fb_authentication.src.dir}/
    AuthenticationModule.mxml"
    output.file="${release.dir}/AuthenticationModule.swf"
    />
  <compile_module
    input.file="${asabau_cg3_fb_album.src.dir}/AlbumModule.mxml"
    output.file="${release.dir}/AlbumModule.swf"
    />
  <compile_module
    input.file="${asabau_cg3_fb_shell.src.dir}/MainLauncher.mxml"
    output.file="${release.dir}/MainLauncher.swf"
    />

  <custom_html_wrapper
    template.dir="${asabau_cg3_fb_shell.src.dir}/../html-template"
    input.file="index.template.html" output.file="MainLauncher.html"
    application="main"
    title="Facebook Photo Gallery Using Parsley Application Framework"
    swf="MainLauncher" width="1000" height="700" bgcolor="#FFFFFF"
    />
</target>

Before starting to compile the main launcher, some preparation tasks are performed via depends property:

• init – deletes and recreates the app release directory
• compile_api – compiles asabau_cg3_fb_api into an external swc file
• copyRSLs – generates and copies all required rsls to the project release directory

A .swf runtime shared library (rsl) is generated from a swc file by the create-rsl ant macro. A swc file is just an archive containing among other things a library.swf file. This library.swf file represents the runtime-shared-library. One needs to extract library.swf, optimize it to minimize size, update its flex digest signature to prevent runtime conflicts between libraries.

<macrodef name="create-rsl">
  <attribute name="rsl-dir"/>
  <attribute name="swc-dir"/>
  <attribute name="swc-name"/>

  <sequential>
    <unzip src="@{swc-dir}/@{swc-name}.swc" dest="@{rsl-dir}" >
      <patternset>
        <include name="library.swf" />
      </patternset>
    </unzip>

    <exec executable="${flex.optimizer}" failonerror="true">
      <arg line="-input @{rsl-dir}/library.swf
      -output @{rsl-dir}/@{swc-name}.swf"/>
      <arg line="-load-config ${basedir}/asabau_cg3_fb_config.xml"/>
    </exec>

    <delete file="@{rsl-dir}/library.swf"/>

    <exec executable="${flex.digest}" failonerror="true">
      <arg line="-digest.rsl-file  @{rsl-dir}/@{swc-name}.swf"/>
      <arg line="-digest.swc-path  @{swc-dir}/@{swc-name}.swc"/>
    </exec>
    </sequential>

</macrodef>

External modules are compiled using an ant macro like the one below. This makes sense because all external modules need to be compiled against the same external libraries, using the same method.

<compile_module
    input.file="${asabau_cg3_fb_authentication.src.dir}/
    AuthenticationModule.mxml"
    output.file="${release.dir}/AuthenticationModule.swf"
/>

A custom html wrapper macro – custom_html_wrapper – is being used because Flex 3 html-wrapper task doesn’t support generation of custom html code. In this case, swfobject and facebook html/javascript code is required in the main html launcher. This macro just parses an html file replacing all html occurrences of several key elements like ${swf}, ${title} with the input parameters. These elements are found in the exact same form in standard flex html-template/index.template.html files.

<custom_html_wrapper
    template.dir="${asabau_cg3_fb_shell.src.dir}/../html-template"
    input.file="index.template.html"
    output.file="MainLauncher.html"
    application="main"
    title="Facebook Photo Gallery Using Parsley Application Framework"
    swf="MainLauncher" width="1000" height="700" bgcolor="#FFFFFF"
/>

This post is part of Facebook Photo Gallery.

Detailed steps.
FB.Facebook.init from the javascript API is responsible for checking whether or not a Facebook session is already active for the current user. In a standard javascript scenario, this function is being called automatically after the html page finishes loading. In our case, FB.Facebook.init is called from the flex app once all its external modules and runtime shared libraries are loaded.

From asabau_cg3_fb_shell, MainLauncher.mxml

// flex app is ready now, time to init the FB session
dispatchEvent(SessionEvent.newInitEvent());

This session event is handled in asabau_cg3_fb_api, FBSession.as

[MessageHandler(selector="fbInit")]
public function init():void {
	ExternalInterface.addCallback("sessionUpdate", sessionUpdate);
	ExternalInterface.call("init", API_KEY);
}

First we register for the app swf object a sessionUpdate javascript handler. When sessionUpdate function is called on the embedded html swf object in javascript, a corresponding sessionUpdate function from FBSession.as will be called in flex. This sessionUpdate function will be called every time the Facebook session changes its status via init, login, logout Facebook operations.

Once the flex app has the means to listen for javascript Facebook session update events, it triggers a Facebook session initialization by calling javascript function init

function init(api_key) {
    FB_RequireFeatures(["Api", "Connect"], function() {
        FB.Facebook.init(
            api_key,
            'xd_receiver.htm',
            {
                "ifUserConnected": sessionUpdate,
                "ifUserNotConnected": sessionUpdate
            }
        );
    });
}

Results from the FB.Facebook.init javascript call are handled in javascript function sessionUpdate, responsible for propagating the changes to the flex app.

function sessionUpdate() {
	swfobject.getObjectById("flashContent").sessionUpdate(
		sessionInfo()
	);
}

The flex app receives a sessionInfo object constructed in javascript using the Facebook actionscript API

function sessionInfo() {
	var info = FB.Facebook.apiClient.get_session();
	return info;
}

FBSession.as from asabau_cg3_fb_api determines if a valid javascript Facebook session has been established in its corresponding sessionUpdate actionscript function. If it does, based on the established javascript session an actionscript session is created that will be used for all Facebook related calls – getting user info, public albums and photos.

public var facebook:Facebook;
public var session:WebSession;

public function sessionUpdate(sessionData:Object):void {
	...
	session = new WebSession(
		API_KEY,
		sessionData.secret,
		sessionData.session_key
	);
	session.facebook_internal::_uid = sessionData.uid;

	facebook.startSession(session);
	session.verifySession();

SessionController.as from asabau_cg3_fb_authentication handles all actionscript session events including FacebookEvent.CONNECT.

protected function onConnect(event:FacebookEvent):void {
	...
	dispatchEvent(UserDataEvent.newLoadEvent());
	...
}

This UserDataEvent signals the flex app has reached a state when it’s now possible to query the Facebook servers via Facebook actionscript API to get user first and last name, public albums and photos, etc.

Login and logout events are being dispatched via the Parsley framework eventually reaching FBSession.as

public function login():void {
	ExternalInterface.call("connect");
}

public function logout():void {
	ExternalInterface.call("logout");
}

The corresponding javascript calls making use of Facebook Connect javascript API:

// trigger connect popup
function connect() {
	FB.ensureInit( function() {
		FB.Connect.requireSession(null, true);
	});
}

// terminate all FB sessions
function logout() {
	FB.Connect.logout();
}

This post is part of Facebook Photo Gallery.

For example, for the AlbumModule we have the following mxml configuration files:

• AlbumModuleLauncherContext.mxml – Used by AlbumModuleLauncher for separate testing of AlbumModule. Contains objects outside AlbumModule needed to initialize the AlbumModule.
• AlbumContext.mxml – Contains objects needed by AlbumModule.

From AlbumContext.mxml:
<pres:AlbumPM />
<pres:PhotoPM />

<domain:AlbumList />
<domain:PhotoList />
<fb_domain:AlbumData />
<fb_domain:PhotoData />

<app:LoadAlbumListCommand />
<app:LoadPhotoListCommand />
<app:SavePhotoCaptionCommand />


All of the above objects are now part of the IOC Container and will be managed by the Parsley framework. There are presentation models, model objects, command classes. All can now make use of Parsley dependency injection and messaging framework.

2. Initialization
Via mxml tags, in each module top view, we specify the configuration file context location via ContextBuilder and then initialize the IOC Container via Configure.
<parsley:ContextBuilder config="{AlbumContext}" id="context" />
<parsley:Configure />

The IOC Container configuration happens before creationComplete, this is a useful information when you want to dispatch framework registered events from the parent container to the child module. Using the <parsley:Configure /> tag you know for sure that when creationComplete is triggered, IOC container and all its objects have been initialized. It’s now safe to dispatch events in the parent container, they’ll be handled in the child module.

3. Dependency Injection
Each object from the IOC Container can make use of the [Inject] metadata tag and most of them do. From LoadAlbumListCommand:
[Inject]
private var fbSession:FBSession;

This injects a FBSession singleton in the command class. Other classes injecting the same variable type FBSession will get the same singleton instance. This is the default behavior, but you can have non singleton variables if needed. For all Album and Authentication classes, fbSession represents the same Facebook session used in all Facebook calls.

Parsley IOC framework is responsible for adding the singleton behavior to the FBSession class at runtime. FBSession class code doesn’t contain any singleton specific code.

4. Messaging
For Parsley framework to handle app custom events you need to mark them as managed events in the object dispatching them, object that is part of IOC Container. This way sender and receiver objects don’t need to know each other, messaging takes place in a decoupled manner. You don’t have to use any specific Parsley methods to dispatch events, you can do it with the standard actionscript dispatchEvent assuming at some point the sender object extends EventDispatcher. Because of this, we can talk about sender and receiver objects being decoupled from the framework as well.

From AlbumPM, presentation model for the view displaying the end user photo albums:
[Event(name="albumSelect", type="com.asabau.facebook.album.AlbumEvent")]
[ManagedEvents("albumSelect")]
public class AlbumPM extends EventDispatcher

From its selectAlbum function

public function selectAlbum(album:AlbumData):void {
	....
	dispatchEvent(AlbumEvent.newSelectEvent(album));
	...
}

All event handling is done in asynchronous Command classes via Command, CommandResult, CommandError tags. Intercept tag is being used to override the Command classes and “fake” CommandResult data. This can be useful when launching standalone modules that rely on other modules for some features. Like AlbumModule requiring AuthenticationModule to establish a Facebook connection before getting the album list. Via Intercept, we can supply a static album list data set to AlbumModule and not rely on AuthenticationModule.

From LoadPhotoListCommand, command triggered when above AlbumEvent.newSelectEvent gets dispatched:

[Command(selector="albumSelect")]
public function execute(event:AlbumEvent):Task {
	...
	return Task;
}

CommandResult and CommandError are invoked automatically by the Parsley framework when the async call represented by the Task object has completed.

[CommandResult(selector="albumSelect")]
public function resultHandler(task:FBCallTask, event:AlbumEvent):void

[CommandError(selector="albumSelect")]
public function faultHandler(
	faultEvent:FaultEvent,
	trigger:AlbumEvent):void

5. Spicelib Task Framework
With Parsley 2.2 Command classes like the one above can now make use of both AsyncToken and Task objects to identify asynchronous calls. This makes a lot of sense because only a few flex async operations are capable of returning AsyncToken objects like, for example, HTTPService.send method.

The Facebook actionscript API doesn’t contain any methods returning AsyncTokens when doing asynchronous server calls. The Task object helps tremenduously here, we get to have the same AsyncToken functionality for any custom async operation.

From FBCallTask
import org.spicefactory.lib.task.Task;
public class FBCallTask extends Task

private function parentCallComplete(event:FacebookEvent):void {
	if (event.success) {
		...
		complete();
	}
	else {
		error(...)
	}
}