Thursday Nov 28, 2013

ADF Debugging Aid: The ADF Request Analyzer

Seasoned Oracle ADF developers will be familiar with the ADF Logging framework, an instrumentation API that you can use to surface what your application is doing behind the scenes, mainly as a debugging aid.  The ADF framework itself uses the ADF Logging framework to produce copious logs showing what the framework actually does for you.

Admittedly reading the logs, either your's or Oracle's can be a rather tedious process.  Let's admit it, reading text files with 1000 of lines of output isn't what we signed up for when we joined the exciting world of the IT industry.  Arguably reading the logs can also be like drinking from a fire hose too, there's just too much information to digest.

To make your life a little easier as a developer, Oracle's JDeveloper includes the Oracle Diagnostic Log Analyzer which is a visual tool included in the IDE designed to allow you to search, filter and read the logs in a structured fashion.

A superb addition to the Oracle Diagnostic Log Analyzer is the ADF Request Analyzer.  The ADF Request Analyzer is not just designed to assist you read the logs, but restructures the logs to represent the JSF & ADF lifecycle on each request.  In other words it moves from a flat line by line log structure which doesn't really represent the flow or logic of how each request is processed, to showing you visually in a tree structure the different phases of the lifecycle processing the request.

Interjecting with one of the main benefits I see from a personal perspective, the ADF Request Analyzer takes that dry JSF lifecycle you read about in books but never really understood as it was all theoretical, and now shows you the runtime representation of the lifecycle so you really get to see what gets processed when.

For customers who don't know about this tool, the ADF product management team has released a new ADF Insider video on the ADF Insider Essentials YouTube channel entitled the Oracle Diagnostic Log Analyzer - ADF Requests and the JSF Lifecycle.  To make it a little more realistic than "here's the tool and you should use it", the video attempts to show you some real running scenarios, as well as how you would use it in a production environment.

We hope you find this useful.  As can be seen Oracle's ADF Product Management team continue to commit to providing customers comprehensive learning collateral on your ADF endeavours, with the ADF Insider Essentials channel, ADF Architecture TV, ADF Mobile Academy and much more.

Image courtesy of artur84 /

Monday Nov 11, 2013

Tip: Keeping the ADF Mobile PDF Guide up to date

This is a little tip for customers using Oracle's ADF Mobile.

If you're like me, it's possible you don't rely on the online HTML version of the Mobile Developer's Guide for ADF, but rather download a PDF version of the file to use locally (look to the "PDF" link to the top right of the guide).  For me the convenience of the PDF is it's faster, I can search the whole document easily, I can split read the document across two pages on my home monitor, if I lose my internet connection the document is still available, and it's easy to read on my iPad (especially on long haul flights to the US across the Pacific where there is no internet connection!).

The trigger point for me to download the Oracle PDF documentation has always been on a new point release of JDeveloper.  However in the case of ADF Mobile, as an extension to JDeveloper it is releasing at a much faster and independent schedule to JDeveloper and this includes updates to the documentation.

As such the ADF Mobile PDF guide you have locally might be out of date and you should take the opportunity to download the latest version.  This is also particularly important for ADF Mobile as not only are many new features being added for each release and included in the new documentation, but the guide is under rapid improvement to clarify much of what has been written to date.  Our documentation teams are super responsive to suggestions on how to improve the guides and this often shows per point release.

How do you tell you've the latest guide? Look to the document part number which right now is "E24475-03".  This is a unique ID per release for the document, the first part being the document number, and the part after the dash the revision number.  If the website document number has a higher revision number, time to download a new up to date PDF.

One last thing to share, you can follow the ADF Mobile guide document manager Brian Duffield on Twitter to keep abreast of updates.

Image courtesy of Stuart Miles /

Wednesday Nov 06, 2013

Diagnosing ADF Mobile iOS deployment problems

From time to time I encounter customers who have taken possession of a brand new Apple Mac, have that excited "I've just spent more on a computer then I ever wanted to but it's okay" crazy gleam in their eye, but on pre-loading all the necessary software for Oracle's ADF Mobile to start their mobile campaign, following Oracle's setup instructions and deploying their first app to Apple's XCode iPhone Simulator they hit this error message in the JDeveloper Log-Deployment window:

[01:36:46 PM] Deployment cancelled.
[01:36:46 PM] ----  Deployment incomplete  ----.
[01:36:46 PM] Failed to build the iOS application bundle.
[01:36:46 PM] Deployment failed due to one or more errors returned by '/Applications/'.  The following is a summary of the returned error(s):
Command-line execution failed (Return code: 69)

"Oh, return code 69, I know that well" I hear you say.  Admittedly the error code is less than useful besides drawing some titters from the peanut gallery.

Before explaining what's gone wrong, I think it's useful to teach customers how to diagnose these issues themselves. 

When ADF Mobile commences a deployment, be it to Apple's iOS or Google's Android platforms, JDeveloper and ADF Mobile do a good job in the Log window of showing you what the deployment process entails.  In the case of deploying to iOS the log window will literally include the XCode commands executed to complete the deployment cycle. As example here's the log output that was produced before the error message was raised.... take the opportunity to read this line by line and note the command line calls highlighted in blue:

(Note some of the following lines have been split over multiple lines to suit reading on this blog, each original line is preceded by a timestamp. Ensure to check the exact commands from JDev)

[01:36:33 PM] Target platform is (iOS).
[01:36:33 PM] Beginning deployment of ADF Mobile application 'LayoutDemo' to iOS using profile 'IOS_MOBILE_NATIVE_archive1'.
[01:36:34 PM] Command-line executed: [/Applications/, -version]
[01:36:34 PM] Command-line execution succeeded.
[01:36:34 PM] Running dependency analysis...
[01:36:34 PM] Building...
[01:36:34 PM] Deploying 3 profiles...
[01:36:35 PM] Wrote Archive Module to /Users/chris/fmw/jdeveloper/jdev/extensions/
[01:36:35 PM] WARNING: No Resource Catalog enabled ADF components found to package
[01:36:36 PM] Wrote Archive Module to /Users/chris/fmw/jdeveloper/jdev/extensions/
[01:36:36 PM] Verifying existence of the .adf source directory of the ADF Mobile application...
[01:36:36 PM] Verifying Application Controller project exists...
[01:36:36 PM] Verifying application dependencies...
[01:36:36 PM] The application may not function correctly because the following dependent libraries are missing: /Users/chris/jdev/jdeveloper/jdeveloper/jdev/extensions/
[01:36:36 PM] Verifying project dependencies...
[01:36:36 PM] Validating application XML files...
[01:36:36 PM] Validating XML files in project ApplicationController...
[01:36:36 PM] Validating XML files in project ViewController...
[01:36:40 PM] Copying common javascript files...
[01:36:41 PM] Copying FARs to the ADF Mobile Framework application...
[01:36:41 PM] Extracting Feature Archive file, "ApplicationController.jar" to
deployment folder, "ApplicationController".
[01:36:42 PM] Extracting Feature Archive file, "ViewController.jar" to
deployment folder, "ViewController".
[01:36:42 PM] Deploying skinning files...
[01:36:43 PM] Copying the CVM SDK files built for the x86 processor...
[01:36:43 PM] Copying the CVM JDK files built for the x86 processor...
[01:36:43 PM] Command-line executed: [cp, -R, -p,
[01:36:43 PM] Command-line execution succeeded.
[01:36:43 PM] Command-line executed: [cp, -R, -p,
[01:36:43 PM] Command-line execution succeeded.
[01:36:43 PM] Copying security related files to the ADF Mobile Framework application...
[01:36:44 PM] Command-line executed from path:
[01:36:44 PM] Command-line executed:
/Applications/ clean install
-configuration Debug -sdk

As you can see when we move from JDeveloper undertaking its work, it then passes the code off in the last few lines for Apple's XCode to assemble and deploy the required .ipa file.  From the original error message which followed this complaining about xcodebuild failing with return code 69, we can quickly see the exact command line used to call xcodebuild.

As this is the exact command line call with all its options, you're free to open a Terminal window in Mac OSX and execute the same command by simply copying and pasting the command line. And via this you'll then find out what return code actually 69 means.  Unfortunately it's not that exciting.

For Macs that have just been installed and configured with XCode, XCode (and for that matter iTunes) which is required by ADF Mobile to deploy must have been run at least once before hand on your brand new Mac (to be clear that's once ever, not once every restart). On doing so you will be presented with a license agreement from Apple that you must accept. Only once you've done this will the command line calls work.  They're currently failing as you haven't accepted the legal terms and conditions. (arguably you an also accept the terms and conditions from the command line too, but ADF Mobile cannot do this on your behalf, so it's just easier to open the tools and confirm the legal requirements that way).

Putting aside the error code and its meaning, watching the log window, watching what commands are executed, learning what they do, this will assist you to diagnose issues yourself and solve these sort of issues more relatively quickly.  From my perspective as an Oracle Product Manager, it allows me to say "this is the stuff you don't need to worry about when you use ADF Mobile when it's configured correctly" .... as you can see my salesman qualities shine through.

For anyone who is happily using ADF Mobile on a Mac and wondering why you didn't hit these issues, it's quite likely that you already accepted the license conditions before deploying via ADF Mobile.  For instance, though I'm not a fan of iTunes itself, iTunes was one of the first things I loaded on my Mac to access my Justin Bieber albums.

Image courtesy of winnond /

Not a selfie
Chris Muir
Oracle Mobility and Development Tools Product Manager

The views expressed on this blog are my own and do not necessarily reflect the views of Oracle.



« November 2013 »