Developing Applications for the BlackBerry Smartphone


Learn how easy this process is using Oracle JDeveloper and Oracle ADF

by Luc Bors

Published May 2010

Downloads:

Oracle Application Development Framework (Oracle ADF) offers a complete framework (design time and runtime) for BlackBerry smartphones that supports two types of mobile applications:  Oracle ADF Mobile Browser applications, which function as a connected Web application running in the BlackBerry browser (these applications can also be customized and optimized to run in that browser); and Oracle ADF Mobile Client applications, which are running in disconnected mode on the mobile device leveraging device-native UI components.  In either case, the development process is the same. In this article, you will learn how easy this process is using Oracle JDeveloper and Oracle ADF. 

Developing a Basic Mobile Browser Application

Developing mobile browser applications for mobile devices with Oracle ADF Mobile Browser client leverages the same methodologies used in developing JSF applications for the desktop, with the addition of a few specific mobile extensions.  Thanks to support in the client for over 60 Apache MyFaces Trinidad components, you can build applications with a rich component set, each of which renders appropriately for small-screen mobile devices. In this manner, you can reuse the desktop browser application's model and controller layers to assemble a new view layer for mobile devices.  Thus, the process of developing a basic mobile browser application is not much different from that of developing a Fusion Web application in Oracle JDeveloper.  (All steps to create a basic Oracle ADF Mobile Browser Application are described here.)

The Trinidad mobile renderers have been optimized to minimize the payload of the Web page sent to the mobile device for improved performance over wireless networks. In mobile environments with high-latency and low-bandwidth wireless networks, Partial Page Rendering (PPR) is essential in providing end-users with an efficient application.  For mobile browsers supporting Ajax,  Oracle ADF Mobile browser client supports PPR for certain components to minimize the amount of data requested from the server and improve the responsiveness of the applications.

Oracle ADF Mobile Browser client has the ability to render applications to older and newer BlackBerry browsers.  When using versions before 4.6, you have to take in account that some features are not supported.

Browser

Javascript Support

CSS Support

PPR Support

BlackBerry version 4.6 and later

Yes

Yes

Yes

Blackberry versions 4.2 through 4.5

No

Yes

No


Table 1 Supported Browsers and Supported Mobile Features

For example, on browsers for BlackBerry 4.5 and earlier,  the bullets in a list sublevel (such as those in a tr:panelList component) appear abnormally large.  The BlackBerry browser’s table handling may affect complex layouts; the BlackBerry browser does not allow horizontal scrolling.  Instead, it wraps a table row onto multiple display lines which may disturb the layout.

Although Javascript is not delivered to the older BlackBerry browsers, the mobile renderer will deliver plain HTML content to BlackBerry browsers 4.2 to 4.5..

Chapter 6 in the “Mobile Browser Client Developer's Guide for Oracle Application Development Framework” goes in to the specifics of how to accommodate the behavior of RIM BlackBerry browsers 4.2 to 4.5.

Optimizing an Oracle ADF Mobile Browser Application for BlackBerry

Although the application you create when following these steps is optimized for running in Mobile Browsers, it is not yet optimized to render optimally in a BlackBerry browser.

 


Mobile Browser Application

What you will see is that the look and feel is not even close to that you would expect to see on a BlackBerry device.  Also the user experience is not yet optimal.  However, there are some steps you can take to ensure a “real” BlackBerry experienc e.

Skinning One of the steps to optimize the user experience is to use skinning.  Skinning allows an Oracle ADF Mobile Browser application to deliver a BlackBerry-optimized user interface using Trinidad components.  It also allows the same set of UI components to take on a look-and-feel optimized for BlackBerry smartphones, without needing to create multiple versions of the same application for different mobile devices.  To have the application use a blackberry skin, it must be configured to do so.

The first step in skinning for BlackBerry is to implement logic that would allow a JSF application to apply different style sheets for different mobile browsers during run time.  Because 4.2-4.5 browsers get the plain HTML content, which changes the page layout, you may want to use different CSS for 4.2-4.5 and 4.6+ browsers.  To support that, you need to find out the actual device type that the application is running on.  This information is available from within the request. 

In the trinidad-config.xml file you can set the <skin-family> element to determine which skin to use. For that you can use the EL expression #{requestContext.agent.skinFamilyType}. This would return blackberryminimal for 4.2 to 4.5 browsers, and blackberry for 4.6 (i.e. JS enabled) browsers.

<?xml version="1.0" encoding="windows-1252"?>
<trinidad-config xmlns="http://myfaces.apache.org/trinidad/config">
<skin-family> #{requestContext.agent.skinFamilyType} </skin-family>
</trinidad-config>  

You have to create the various skin families in the trinidad-skin file, as well as the corresponding location of the CSS file within the project.  If there is a skin family that’s not listed in the trinidad-skin file, then Oracle ADF will just deliver the default skin file.  The entries for BlackBerry would be:

<skin>
        <id>blackberry4_2</id>
       <family>blackberryminimal</family>
        <render-kit-id>org.apache.myfaces.trinidad.pda</render-kit-id>
       <style-sheet-name>styles/blackberry4_2.css</style-sheet-name>
   </skin>
<skin>
      <id>blackberry4_6</id>
<family>blackberry</family>
<render-kit-id>org.apache.myfaces.trinidad.pda</render-kit-id>
<style-sheet-name>styles/blackberry4_6.css</style-sheet-name>
    </skin>


Besides skinning,  Oracle ADF provides framework features that help developers to create applications that are optimized for BlackBerry browsers.   As you might know, the BlackBerry browser behaves differently than many other browsers in that it does not display pages using horizontal scrolling.  Instead, it fits a page to the width of the screen.

Optimizing Browser Page Layout. In order to create an optimal layout for the BlackBerry you can use styleClasses.  These styleClasses can be set in the styleClass property of the components on the page.  You can for instance create a typical BlackBerry toolbar for the application, just like the one below.

 


BlackBerry Browser Look and Feel
<tr:panelHeader styleClass="af_m_toolbar" text="Transfer">
            <tr:commandLink styleClass="af_m_backButton" 
                            text="Back"
                            action="back"/>            
            <tr:commandLink styleClass="af_m_button"
                            text="Sign Off"             
                            action="signoff"/>
</tr:panelHeader>


These styleClasses have to be defined in the stylesheet associated with the skin you use.  The af_m_button in the code fragment above is defined like this:

.af_m_toolbar .af_m_button {
  position: absolute;
  right: 10px;
  text-align: center;
  vertical-align: middle;
  text-decoration: none;
  padding: 5px 0px;
  width: 70px;
  height: 25px;
  overflow: hidden;
  border-width: 0px;
  font-size: 13px;
  font-weight: bold;
  color: #FFFFFF;
  background: url(/images/toolButton.png) no-repeat transparent;
  white-space: nowrap;
}


If all the styles are defined properly, and applied to the components in the correct way, you can achieve a BlackBerry look and feel.

 


Optimized Mobile Browser Application

Server-Side integration with BlackBerry Enterprise Servers.The BlackBerry Enterprise Server is designed to be a secure, centralized link between an organization's wireless network, applications, and BlackBerry devices.  This involves functionality such as messaging and collaboration software and custom applications, to provide BlackBerry device users with mobile access to your organization's resources.  Oracle ADF Mobile Client integrates with the BlackBerry Enterprise Server.

For device management and application provisioning,  Oracle ADF Mobile Client can also leverage device-native management solution such as BlackBerry Enterprise Server, allowing IT administrators to use the existing toolset to manage an Oracle ADF Mobile Client application.  BlackBerry Enterprise Server v5.0 features built-in over the air software loading which simplifies wireless deployment of BlackBerry smartphone software.  (For more details and examples on BlackBerry Enterprise Server go to the BlackBerry Developer site.)

Developing BlackBerry-Native Applications Using Oracle ADF Mobile Client

Oracle ADF Mobile Client is a mobile implementation of the Oracle ADF Model-View-Controller architecture that lets you build an on-device, native mobile application for the BlackBerry smartphone.  For scenarios where there is a need for deep integration with the capabilities of the mobile device, or to work in a disconnected mode, Oracle ADF Mobile Client is the appropriated development approach.

Oracle ADF Mobile Client consists of a client part that includes a mobile Model,  Controller,  View,  and J2ME runtime.  There’s also a Model that includes the local relational database and the mobile BC4J layer as shown in Figure 4.

 


Oracle ADF Mobile Client Architecture


The Oracle ADF Mobile Client’s Model-View-Controller stack resides on the BlackBerry device and represents reimplementation of Oracle ADF’s model-view-controller layers.  UI metadata is rendered to native components on-device and is bound to the model through JSR 227.

Figure 5 shows how the runtime architecture for Oracle ADF Mobile Client Applications fits in the overall architecture (on the right in red).

 


Oracle ADF Mobile Client Architecture

The application infrastructure for Oracle ADF Mobile Client Applications is shown in Figure 6.

 


Oracle ADF Mobile Application Client Architecture


The Oracle Lite Mobile Server is used to manage synchronization to the server database. 

Oracle ADF Mobile Client Support for BlackBerry Smartphones

Oracle ADF Mobile Client offers full support to run on BlackBerry smartphones from version 5.0 or above.  You can deploy Oracle ADF Mobile Client runtime from within JDeveloper by selecting the tools - Deploy Oracle ADF Mobile Client Runtime - menu item in Oracle JDeveloper.

 


Deploy Oracle ADF Mobile Client Runtime

When deploying the Oracle ADF Mobile Client Runtime to the BlackBerry device, a couple of files are copied to the device.  These are COD files, which are file extensions for Blackberry libraries. 

 


Deployed Files

These libraries are responsible for implementing the Oracle ADF Mobile Client framework functionality such as Oracle ADF model and Oracle ADF databinding, as well as the Oracle ADF User interface.  There is also a library containing utility classes and some XML functionality, and finally the synchronization support and the on device SQLite database implementation.

Developing an Oracle ADF Mobile Client for BlackBerry, Step by Step

Developing an Oracle ADF Mobile Client application would usually involve the following steps:

  • Create an Oracle ADF library for Business Components (when you are extending a server-side Oracle ADF application to mobile).
  • Create a new Oracle ADF Mobile Client Application workspace in JDeveloper. 
  • Create Oracle ADF Mobile Client Businesses Components.
  • Create the Oracle ADF Mobile Client User Interface.
    • Define the mobile taskflow
    • Create Mobile Application Pages
    • Define Mobile Application Menus
  • Deploy the Application
  • (Optional) Setting up Data synchronization


Before you can start you need to download and install the required software.

Optional Downloads:


Step 1: Create Oracle ADF Library For Business Components

The typical development scenario is to extend a “base” Oracle ADF application.  Before you create the client application, the business components of the base Oracle ADF application have to be deployed to an Oracle ADF library. This library will be the base for the mobile client business components.

For that we have to create a new deployment profile, an Oracle ADF Library JAR file.

 


Create Deployment Profile


With the deployment profile in place, now deploy the business components project to an Oracle ADF library.

 


Deploy to Oracle ADF Library


Step 2: Create a New Application Workspace

The Oracle ADF library containing the base applications business components will be the base for the Oracle ADF Mobile Client Application. 

An Oracle ADF Mobile Client application can be developed in Oracle JDeveloper using the Oracle ADF framework.  The first thing you need to do is to download the Oracle ADF Mobile Client extension.   To download this extension, go to Help > Check for Updates in JDeveloper.  The extension can be found under Official Oracle Extensions.

 


Download extension


After installing the extension, Oracle JDeveloper needs to be restarted.

With the extension installed you will notice that there are some new options in the New…..  gallery.   The one needed is Mobile Client Application (Oracle ADF).

 


New Mobile Client Application


This will create an application workspace contains of an empty model project and a preconfigured Mobile Client project.   The first will contain the business components in the final application;  the latter will contain page flows and the Mobile Client interface.

 


Application Content


Step 3: Create Default Business Components

The next step in the development process is to create business components.

For version 1 of the Oracle ADF mobile client there are some limitations to the functionality of business components  in comparison to standard Oracle ADF business components.   While developing an Oracle ADF Mobile Client application you have to keep this in mind:

  • Client Entity Objects are copies of a subset of the Entity Objects of the Base Application.
  • View Objects must be based on Entity Objects or be static VO.
  • Subset of EO and VO functionality is supported.

Also be careful when defining a VO based on a SQL statement.  Only use the tables and fields available on the mobile device.  When you define a SQL based VO,  Oracle JDeveloper actually checks against the server database, and not against the client database, because client database is not there yet.   Be careful not to pick objects that are not brought down to the mobile database.

Open the New Gallery and create new Oracle ADF Mobile Client Business Components from Entity Objects.

 


New Oracle ADF Mobile Client BC from EO


In the wizard find the appropriate Oracle ADFLibrary (the one that contains the Business Components from the Base Application) by using the Browse… button.  Once you found the Oracle ADFLibrary, use the Import… button to import all the Entity Objects from the Oracle ADFLibrary into the Mobile Client Project.  You can shuttle all the necessary entity objects from “Available:” to “Selected:”.

 


Select Entity Objects to use


Once the necessary entity objects have been selected, click next to go to the next page of the wizard.

Click next on page 2 of the wizard, and on page 3 select all available objects and shuttle them from available to selected, in order to create updatable view objects for all of them.  Click Finish to close the wizard.  The default model project for the mobile client application is now ready.

Step 4: Design the Taskflow and Pages

When the Oracle ADF Mobile Client Application was initially created,  Oracle JDeveloper also created an empty MobileClient-taskflow file in the mobile client project.  This taskflow can be used to design the page flow for the mobile client application.   The taskflow editor can be opened by double clicking the file.  The activities can be created by dragging them from the component palette to the taskflow diagram.   It works exactly the same as when developing a standard Oracle ADF Application.   There are a few limitations to keep in mind though.  By default only one task flow per application is supported, and you cannot create multiple task flows and embed one within another.   Page fragments are also not supported.

The taskflow editor supports wildcards, routers, method calls and taskflow returns.  

The sample application in this article uses a home page as a landing page for the application.  There will be the possibility to browse Personal data on the BrowsePerson page, and the application supports browsing and editing orders.  A wildcard activity is added to go to the home page from anywhere and another one to support exiting the application from anywhere.  The exclamation marks in the diagram indicate that the corresponding pages are not yet created, but they will disappear as soon as they are.

 


Taskflow Overview


You can create the pages from within the taskflow diagram.  Create the empty home page by double clicking it.  A popup appears where the page can be given a name.  By default the name is the same as the activity name in the taskflow.

 


Create Pages


Notice the extension of the page being mcx.  In an Oracle ADF Mobile Browser Application the extension of the page files is jspx.  So the mcx extension is typical for Oracle ADF Mobile Client Applications.

Continue creating default pages for the remaining view activities in a similar way.

Step 5: Adding Databound UI Components to the Pages

You can create databound UI components in an MCX view by dragging data controls from the Data Control panel and dropping them into either the Structure window or the code editor.   When you drag an item from the Data Controls panel to either of these places,  Oracle JDeveloper invokes a context menu of the default UI component available for the item that you dropped.  Oracle JDeveloper generates the mappings that determine which controls can be inserted into an MCX page.  In addition, the IDE creates the binding information in the associated page definition file.  If no such file exists, then Oracle JDeveloper creates one.  The UI components are bound to the model through JSR 227.

The basic development process of a databound user interface is demonstrated by adding components to the BrowsePerson page.   The BrowsePerson page is a databound page that gets its information from the Person collection.   Select the PersonsView1 Collection in the datacontrol palette and drag it onto the BrowsePerson pages structure window.   In the context menu that appears select Forms…Read-only Form….

 


Create Read Only Form


An edit form field dialog is invoked where you can make a selection of all available attributes.   Delete some of the attributes as not all will be used in the BrowsePerson page.   Make sure to check the “include navigation buttons” checkbox.   This will add buttons to the page to browse to next, previous, first and last records.   A submit button is not needed, as this is a read only page.

 


Edit Form Fields


That is all you need to do to create you first basic Oracle ADF Mobile Client page.

Step 6: Creating Buttons And Menus

The landing page of the application will be the “homepage”.   To make “all” the other pages in the application available from within that “homepage” you need to add some navigation components to the home page.  Start with adding the first button on the “homepage”.  This button will be used to invoke the navigation activities that were defined on the taskflow, in the case the button will navigate to the BrowsePerson page.

 


Insert Buttons


After the button is created open the property inspector for the button.  In the property inspector select the action attribute and select the appropriate action form the dropdown list.  In this case the action is “b-Per”.

 


Edit Action Property


When the user pushes the button in the application navigation to the browsePerson page will be invoked.  Add buttons for all other navigations on the “homepage” in a similar way.

<amc:panelGroupLayout  id="pGL1">
      <amc:commandButton text="Browse Person"  action="b-Per" id="cB1"/>     
     <amc:commandButton text="Browse Orders"  action="b-Ord" id="cB2"/>
     <amc:commandButton text="Exit"           action="exit"  id="cB3"/>
    </amc:panelGroupLayout>


It would be very convenient if these actions could be invoked from the BlackBerry main menu as well.  In order to achieve this you simply add Command Menu Items to the page.  Command Menu Items are action components as well and can invoke navigation.  They can be added in the same way as the buttons that were added before.

 <amc:menu type="main" id="menu0">
   <amc:menuGroup id="menuGroup1">
     <amc:commandMenuItem label="Browse Person" action="b-Per" id="cMI1"/>
    <amc:commandMenuItem label="Browse Orders" action="b-Ord" id="cMI2"/>
     <amc:commandMenuItem label="Exit"          action="exit" id="cMI3"/>
   </amc:menuGroup>
 </amc:menu>


Step 7: Creating Browse and Edit Order Pages

The final step in developing this demo Oracle ADF Mobile Client Application is to finish the two pages for browsing and editing orders.  These pages are already created but still empty.  The first page to take on is the browseOrders page.  Drop the Orders1View1 from the datacontrol on the structure window and select read-only table form the popup menu.

 


Create Read Only Table


In the Edit Table Columns delete all items that are not to be included on the browseOrders page..

 


Edit Table Columns


Because navigation to the editOrders page is required, there is a need for a navigation component.  This can be achieved by converting the orderId textfield to a commandlink that invokes navigation to the edit orderPage.  In the sourceView tab of the page editor this can be achieved.  Make sure the action points to “e-Ord”..

<amc:commandLink text="#{bindings.OrderId.inputValue}"
                           action="e-Ord" 
                           id="outputText1"/> 


Finally create the editOrders page by dropping the order collection as a form.  In the Oracle ADF Mobile Client Application there will only be a few changeable items.  In this case only the items selected in the image below are editable.  Remove all others. 

 


Edit Form Fields


An order without it’s order lines is not very interesting.  To add some more information to the order you can add the order lines as a detail table for the order form.  Select the OrderItems1View2 collection in the data control palette and drop it on the editOrders page.  Make sure to select the correct order item collection (i.e.  the child collection of the Orders1View1).  This will automatically display the order lines belonging to the selected order.

 


Create Table


Select only those columns that need to be in the order lines table..

 


Edit Table Columns


STEP 8: Adding Commit and Rollback functionality

In order to commit or rollback any changes to the database, the editOrders page needs buttons or links to invoke this functionality.  This can easily be achieved by dropping both the commit and rollback operations from the datacontrol on to the editOrders page.

 


Add Commit and Rollback


Finally add one more button so that the editOrders page can navigate back to the browseOrders page.  Optionally add command links to the BlackBerry menu for each command button so that these actions can also be invoked from the BlackBerry Menu.

The Oracle ADF Mobile Client Application is now ready for deployment.

STEP 9: Deploying the application

Before deployment, you need to set up the Mobile Client Preferences.  Oracle JDeveloper needs to be able to locate the BlackBerry JDE directory, the BlackBerry Simulator directory and the Olite directory in order to do a successful deployment.

 


Mobile Client Preferences


On the Mobile Client project in Oracle JDeveloper select deploy…. from the mouse menu.

The first time you deploy the application you have to create a new deployment profile.  In the new gallery, pick Oracle ADF Mobile Client for Blackberry.

 


New Deployment Profile


Give the profile a name so it can be identified at any time.

 


Create Deployment Profile


Accept all the default settings in the deployment profile, except for the part where you configure Application Data Publication.  Here you need to configure to connection to the Oracle Mobile Server in order to create the appropriate publication items during Application Data Publication.

Here you have two options: Option one is to configure the Database Connection for the Mobile Server and the Mobile Server Login Credentials for Synchronization.  Also you need to provide a valid name for the On Device Database. 

 


Application Data Publication


The other option is to use a pre-created Mobile Client Database.  You can download such a pre-created Mobile Client Database from the Oracle Technology Network Website at the Oracle ADF Mobile homepage.  This database works with most mobile client applications that are based on the Fusion Order Demo. 

If you go for this option, you do not need to enter the DB connection in the deployment profile.  You have to set enter the full path for the Device Database Name to the location where you downloaded the pre-created Mobile Client Database.

 


Using a full path to a Device Database


Now you are ready to deploy the application to the BlackBerry device (or simulator) so it can be tested in the BlackBerry.  On the mobileClient project in JDeveloper select deploy…. from the mouse menu.  You will find several deployment actions listed.  Pick Deploy to Device.  If you have a simulator running, the wizard will deploy the application to the simulator, unless you have an actual device connected.  The option Deploy to Package is needed when you are deploying to multiple devices using BlackBerry Enterprise Server.  

 


deploy.png


Click Finish to deploy the mobile application to a BlackBerry deployment package.

You can also deploy the application directly to a BlackBerry device.  If you have an actual device connected, the application will be deployed to the BlackBerry.  However, you will need to invoke the BlackBerry signature tool first.  Your application must be signed using a signature key (provided by RIM) before you can load the application .cod files onto the BlackBerry smartphone.

To request code signatures, perform the following actions:

  • Request signature key from BlackBerry,  at http://na.blackberry.com/eng/developers/javaappdev/codekeys.jsp
  •  Make sure the necessary signing files are copied to the BlackBerry Java Development Environment installation location.
  • Open deployment profile, and check the “launch signature tool”, “automatically request signature”, “close tool after requesting signature”, and “close tool after requesting signatures, no error” check boxes (Figure 34).

 


BlackBerry options


Deploy, and fill in the necessary information.  The application will get signed.

Optional steps: Configuring Data Synchronization

This step assumes you have a fully configured Oracle Lite implementation on the database server.

Your Oracle ADF Mobile Client project has been defined, but you still need to specify which data from the server gets synchronized with the client database on the mobile device.  To do this, you create publication items.  Each publication item defines one table on the mobile device and is mapped to a table in the server schema.

In the Deployment Profile you need to specify database connection for the mobile server repository, and a test sync user ID and password.  This is shown in figure 31where you configure the application for synchronization.

To create publication items you simply need to invoke the deployment wizard from within the Mobile Client project.  Once in the wizard, pick Publish Application Data.

 


Publish Application Data

The Deploy wizard automatically creates the publication items corresponding to the table and columns in the application and from the server schema.  Once all of your publication items have been defined, they are automatically grouped together in a publication, and published to the database server.  The publication defines the schema for your mobile application.

In the Deployment Log in Oracle JDeveloper you can monitor the process and see what publication items are being created.  Oracle JDeveloper generates a ‘Mobile Workbench” project file (*.mpj).  You will find this file in “<Jdev App File>\Model\mobile\<package name>\<application name>.mpj “.  You also might want to check the publication status in the Oracle Mobile Database Workbench. 

You now can deploy the application (see previously), run it on the device and try to synchronize with the database server.  If you do not already have a database on the device, the first time you invoke the synchronization on the device, an on device database will be created.

Conclusion

Oracle JDeveloper and Oracle ADF enable developers to extend the reach of their enterprise applications to mobile devices.  By leveraging the same set of skills, same development tool, and same development framework used for regular application development, Oracle JDeveloper and Oracle ADF dramatically lower the learning curve typically associated with mobile application development. 

Additional Resources

The following resources will help to get started on BlackBerry development using Oracle ADF and Oracle JDeveloper today:



Luc Bors
is Expertise Lead Oracle ADF and technical specialist/architect at AMIS, Nieuwegein (The Netherlands). He developed several Workshops and training on Oracle ADF and also is an Oracle ADF and Oracle JHeadstart instructor. Luc is a member of the Oracle ADF Methodology group and publishes articles on Oracle ADF in Oracle technology related magazines, on the AMIS technology blog.