The Oracle documentation describes the use of Ant tasks for automatic deployment to the OAS. For more information on Ant tasks you can find an URL at the end of this post to the online Oracle documentation for the OAS, version 10.1.3.
Versions 10.1.2 and earlier of the OAS have a different method for automatic deployment of the .ear to the server. This happens through a ‘Oc4jDcmServletAPI’ and will not be discussed here.

Below you will find an example script regarding the use of Ant tasks:

<?xml version=”1.0″ encoding=”windows-1252″ ?>
<project name=”XXX” default=”redeploy” basedir=”.” xmlns:oracle=”antlib:oracle”>
<property name=”ear.dir”  value=”${basedir}”/>

<target name=”stop-app”>
<echo message=”Stopping the application”/>
<oracle:stop deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”/>
</target>

<target name=”start-app”>
<echo message=”Starting the application”/>
<oracle:start deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”/>
</target>

<target name=”undeploy-ear”>
<echo message=”Undeploying the application module deployment (ear) file”/>
<oracle:undeploy deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”
logFile=”${basedir}/undeploy-ear.log”/>
</target>

<target name=”deploy-ear”>
<echo message=”Deploying the application module deployment (ear) file”/>
<oracle:deploy deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” file=”${basedir}/${ear.filename}”
deploymentName=”${app.name}” bindAllWebApps=”default-web-site”
contextRoot=”${context.root}” logFile=”${basedir}/deploy-ear.log”/>
<oracle:bindWebApp deployerUri=”${deployer.uri}” userId=”${oc4j.admin.user}”
password=”${oc4j.admin.password}” deploymentName=”${app.name}”
webModule=”${war.filename}” webSiteName=”${oc4j.binding.module}”
contextRoot=”${context.root}”/>
</target>

<target name=”redeploy”>
<input message=”Which release number are you deploying?” addproperty=”ear.version” />
<input message=”To which environment are you deploying? ” addproperty=”deploy.environment”/>

<property name=”ear.location” value=”<repository> /${ear.version}/”/>
<property name=”ear.filename” value=” ear-${ear.version}.ear”/>
<property name=”war.filename” value=”viewController-${ear.version}”/>

<get src=”${ear.location}${ear.filename}” dest=”${basedir}/${ear.filename}”/>

<property file=”deploy_${deploy.environment}.properties”/>

<ant target=”undeploy-ear”/>
<ant target=”deploy-ear”/>
<ant target=”stop-app”/>
<ant target=”start-app”/>

<delete file=”${basedir}/${ear.filename}”/>
</target>
</project>

The code explained

In this example there are a couple of  preconditions. The released ear is to be found in the project repository and needs to be download from there. This example also took into account that you may want to redo a deployment, for example. Therefore the script doesn’t deploy the ear automatically after a build, but you can manually start the script and choose which released ear you want to deploy to which environment.  The following bullets explain the Ant script:

1. The script contains Ant targets per action (stop, start, undeploy, deploy).
2. ‘redeploy’ is the default target if the script is executed. This target actually executes all the steps to reploy the ear on the OAS:
   1. input is asked which version needs to be deployed
   2. input is asked to which environment needs to be deployed
   3. the right ear is downloaded from the repository to the local deployment directory
   4. the current deployment get undeployed from the right OAS
   5. the new ear gets deployed to the right OAS, to the right OC4J instance
   6. the OC4J instance gets stopped
   7. the OC4J instance gets started
   8. the new ear is removed from the deployment directory
3. In  the script properties of the chosen environment are being used, these are collected from the properties file in the deployment directory:

deploy_<environment>.properties:

# The JSR88 deployer URIs. Valid URIs are:
# 1- Oracle Application Server Cluster URI::
#   deployer:cluster:opmn://opmnHost[:opmnPort]/oc4jInstanceName
# 2- Oracle Application Server Single Instance URI:
#   deployer:oc4j:opmn://opmnHost[:opmnPort]/oc4jInstanceName
#   deployer:oc4j:opmn://opmnHost[:opmnPort]/asInstanceName/oc4jInstanceName
# 3- OC4J URI:
#   deployer:oc4j:[host]:[rmiPort]
deployer.uri=deployer:oc4j:opmn://<host>:<6003>/< iASInstanceName>/<OASInstanceName >

# The administrative login name for the target OC4J instance
oc4j.admin.user=oc4jadmin

# The administrative password for the target OC4J instance
oc4j.admin.password=<password>

# The application name within the target OC4J instance
app.name=<application_name>

# The context root of the OC4J application (including the ‘/’)
context.root=/<context-root>

# The web site to which the deployed web modules are bound
oc4j.binding.module=default-web-site

It can be a bit of a search as to fill in the right properties. Therefore I would like to provide some images as a tool to find the right properties in the OAS Enterprise Manager.

Image 1

Image 2

Image 3

When running the Ant script, be aware that the OC4J Ant tasks utilize the ant installation that is shipped with the local JDeveloper 10 installation. For one there has to be a system variable ANT_HOME that points to the ant home in the JDeveloper installation (for example C:\JDeveloperADF10\ant). As a second the system variable PATH needs to contain the path to the ..\ant\bin directory of the local JDeveloper 10 installation (for example C:\JDeveloperADF10\ant\bin). Of course this can also be scripted in the command file to start the Ant script.

Oracle Documentation
De following URL guides you to the Oracle documentation “Oracle® Containers for J2EE Deployment Guide 10g Release 3 (10.1.3)”. This documentation contains a chapter about the method used here: “Deploying with the OC4J Ant Tasks”:

http://docs.oracle.com/cd/B25221_05/web.1013/b14431/toc.htm

First of, the consensus seems to be: do not use Interface Builder! IB gives you all kinds of challenges surrounding AutoLayout. Everyone has their own reasons for this but in short, when you use AutoLayout in code/manually, you are actually in control. So then how do we do this?

Apple has given us a nice, albeit somewhat lenghty way of setting these constraints:

[NSLayoutConstraint constraintWithItem:label
                             attribute:NSLayoutAttributeCenterX 
                             relatedBy:NSLayoutRelationEqual 
                                toItem:tab
                             attribute:NSLayoutAttributeCenterX 
                            multiplier:1.0 
                              constant:0]

Using this to place a button on a UIView the could would look like this:

The first thing to notice is the fact that the second constraint could be formulated differently while getting the same result. In the code example I define the horizontal position of the button to lead the left edge of the superview by 50. However, if I changed the first attibute to NSLayoutAttributeLeft it would instead say that the spacing between the left side of the button and the left side of the superview should be 50. This works because it is inside of the superview. However, if you would want to space two buttons, the second option would not work, this would result in a partial overlap of the buttons since the second button would be placed 50 points from the left of the first button. Instead you would have to use the NSLayoutAttributeRight to define the constraint. If you are planning to use AutoLayout in your applications, make sure you understand the different NSLayoutAttributes and how they affect your components.

Another key element is the following line, if you do not set the TranslatesAutoresizingMaskIntoConstraints to NO/FALSE it will generate it’s own constraints, which will then conflict with yours. So you want to make sure to turn this of for all your components that you define constraints for.

[button1 setTranslatesAutoresizingMaskIntoConstraints:NO];

Unfortunately this leaves us with quite a lot of code if we have to place constraints on a set of UIViews. There are two ways to deal with this excess of code. We can create a category for UIViews that adds some simplified functions to deal with most of the constraints that need to be set. The second option is to use the Visual Format Language(VFL). The latter allows your to use a shorthand notation for your contraints, but more importantly, it allows you to set multiple constraints simultaniously.

To see this in action, lets have a look at a UITextView, if we set it the same way we did with our button we get a black screen, the UITextView will not show up, not even if we set some text. This is because the UITextView does not have have an intrinsicContentSize defined, which means that if you do not tell it what size it should be, it does not know and assumes 0. To fix this we need to set a height and width constraint like in the following example.

UITextView Layout Example

If we would write this in VFL it would look like this:

In the above example you will notice two things, unlike in the earlier examples here I add the UITextView to it’s superview before I set the constraints. We have to do this because within the constraint we refer to our superview implicitely instead of explicitely, which requires us to have a superview before setting the constraint. If you do not do this correctly the app will terminate throwing a NSInvalidArgumentException “Unable to interpret ‘|’ character, because the related view doesn’t have a superview”.

Secondly we now have a dictionary with the views we want to set constraints for, the VFL uses this to refer to the proper UIView object using the keys.

Most importantly though, we now have a shorter way to set our constraints, and we can set all the horizontal or vertical constraints on one UIView at once!

After having reserved my participation in this Masterclass on March 12th, the first day has finally arrived. My colleague Marco Gralike already blogged about the contents of this Masterclass therefore I will not repeat it here. James is well known in the Oracle community, not in the least for his book: Scaling Oracle 8i. That book was recommended to me today by another participant and is available here. I must confess I’ve probably downloaded it years before but have never gotten around to reading it properly. I will make that a priority as I believe now that has been a mistake of mine. The concepts are still valid today as they were then.

Listening to James is very easy to do because he captures your attention with ease. His presentation is a mix of theory, explaining in detail, asking questions to the audience (in order to make us think), and answering our questions. I believe that my understanding of Storage, how it works in detail, how it interacts with the Oracle database, will be much better after also completing day 2. I can hardly wait for tomorrow.

I’ve got lot’s of things to check and verify when I’m back at my “regular” customer. Since I’m, as a member of a lean team, also responsible for the EMC Storage there. That is a benefit of this Masterclass: I shall be able to ask sensible questions to the SAN administrator(s) (But may give the answers myself…). And I should be able to make more sense of the EMC data that is available to us.

Patrick

The architecture is service oriented. Every domain exposes services that provide access to data and business logic. The implementation of these services and the underlying domain is encapsulated. Consumers of the domain services are unaware of the domain internals, therefore they have no dependencies on such internals and will not be affected if the internals change. For as long as the domain adheres to its service contracts, all consumers can continue to function. This even applies if the domain is moved to a different physical location or reimplemented using a COTS (commercial off the shelf) product.

So there we had it: a sound service oriented architecture with fairly strict guidelines and a clear business requirement. The composite service we were tasked with implementing would somehow have to make use of two domain services – one on the CRM domain and one on the SALES domain – to find the customers in the location specified and find all open orders for these customers.

The call to the CustomerService’s findCustomers operation would return a list of customer identifier values. What to do next? Loop over all identifiers and retrieve the orders for the customer identifier – merging all results returned by all calls to OrderServicer.retrieveOrdersForCustomers? Potentially making dozens or more calls to the OrderService? Or perhaps we could transfer the  list of customer identifiers to the OrderService and let it take care of getting all orders for all the customers in the list. But how can we implement this in an efficient manner? How do we prevent executing the query to fetch the orders as many times as there are customer identifiers?

It turned out to be quite simple to address this challenge. Using the Oracle SQL Table Function and the database adapter we can very easily create a SQL query that joins the orders table with the list of customer identifiers. Only a single query is executed against the SALES database and a single round trip suffices to get all order records. The whole approach is of course not as efficient as doing a straight join across the two tables, but in this service oriented context it is not bad at all.

Let’s take a look at the implementation.

Starting at the end

The final result will be like this: three SOA Suite composites are used, one for each of the three services from the original design. Two of these are Domain Services; these use a database adapter to retrieve data from their Domain data store – which happens to be a relational database in both instances.

When the CustomerOrderService is invoked to return all Open Orders for Customers located in the specified location, the BPEL process in the CustomerOrderService Composite will first invoke the CustomerService that – using its database adapter against the CRM database – will return a list of customer identifiers. Next, the BPEL process will use this list of identifiers as input in its call to the OrderService. This latter service is exposed by another SCA composite that has its own database adapter invoking a PL/SQL package. In the call to this package, the entire list of identifiers is passed in. Inside the package, a SQL query is performed (that joins the customer identifiers list to the ORDERS table); this query returns the Orders (for the specified customers and with the appropriate status). The important message is that only one query is performed against the ORDERS table in the SALES database. And regardless of the number of customers involved – it will always be a single query.

Even though the service discussed in this article stretches across two data domains and although joins across these domains are not allowed in SQL queries, we still only required two queries (rather than a single query for each customer). In addition: the consumer of the operation is none the wiser about the underlying structure or whereabouts of the data. Whether the composite service enlisted Cloud based resources, a file system or a number of relational data stores: it is completely hidden from view. As it should be. The remainder of this article demonstrates exactly how this was realized.

Implementation of the CustomerService

Let’s assume a very simple CRM system. A single database table called CUSTOMERS with just four columns. It is enough to serve the purpose of this article. A number of customer records is created in this table.

The CustomerService is implemented using a SOA Suite Composite Application; note: we could just as well have used the Service Bus in this case.

The composite exposes the service with the agreed upon CustomerService interface (described by a WSDL and associated XSD document). A Mediator component implements that interface and maps it to a database adapter service that has been configured to query from the CUSTOMERS table all those customer records that have the required value in their CITY column.

The database adapter configuration is fairly straightforward: the adapter performs a query against table CUSTOMERS and retrieves all records with a CITY value equal to the location parameter.

The Mediator maps the input and output messages specified in the CustomerService contract to the input and output required by the database adapter service based on this configuration.

After deployment, the CustomerService can easily be tested. Given a location, it will return a list of customer identifiers.

Implementation of the OrderService

The implementation of the OrderService takes place at two levels. First at the database level – where a PL/SQL package is created to produce a collection of Order objects based on a collection of Customer identifiers. This package is created, deployed and tested on its own. The second step involves the SOA Suite: a database adapter configuration is created to invoke this PL/SQL package and using a Mediator mapping a pretty service interface to this database adapter the composite is completed, deployed and also tested.

Step one is not SOA Suite specific. The PL/SQL package that returns the collection of Order Records is an example of a encapsulated service – not your typical web service but instead a PL/SQL based API and implementation which is a service just as well. The package contains a SQL query that retrieves records from the ORDERS table. The records are filtered by CTR_ID (the column that contains the customer identifier). This is done using a join to a Nested Table rather than a WHERE condition. Read on, and the what and how are revealed.

The ORDER details are returned from the package as a nested table of objects – using the very powerful yet fairly little known database mechanism of objects and table of objects. Using these next SQL statements, the object and the table of object types are created in the database:

These statements create a type ORDER_TABLE_T – a collection of ORDER_T objects – and ORDER_T itself that describes an object with five attributes. Instances of these objects can be created – in SQL and PL/SQL – and they can be passed around between for example the database adapter and a PL/SQL package.

The package specification that the database adapter will be created against is defined as follows:

The function find_orders is invoked with a number_table_t – defined as CREATE TYPE NUMBER_TABLE_T AS TABLE OF NUMBER – that contains the identifiers of the customers whose orders should be retrieved. Other search criteria are the status of the orders and an upper and lower boundary for the order amount. The function returns an instance of order_table_t – which means it returns a collection of order_t objects.

The implementation of the function is fairly straightforward – if you are familiar with the use of nested table collections, the COLLECT aggregation operator and the TABLE FUNCTION operator in SQL. Note that these features were introduced in Oracle Database 8.0, 10g and 9i respectively. They have been around for a while.

The most interesting part of the function is highlighted in the red rectangle: table ORDERS is joined with something that is not a real table but that behaves as one. Using the TABLE function on the nested table collection with customer identifiers (p_customers_tbl) the query behaves as if a table with customer identifiers does indeed exist (with a single column whose value we access using the pseudo function column_value) and is joined on the CTR_ID column with the ORDERS table. Every ORDER record that is returned by the query is transformed into an OBJECT_T instance. All these OBJECT_T instances are taken together – with the COLLECT operator – and cast to the ORDER_TABLE_T type. An instance of that latter type is what we need – because it is the return type of the function.

A simple test – in PL/SQL – of this function looks like this:

and the output through the server output in this case:

With this PL/SQL package in place, the OrderService is quickly created using a database adapter. Note that the database adapter is remarkably good at dealing with Object Types and Nested Table collections.

The composite is further fleshed out – based on the predefined WSDL and XSD for the OrderService and using a Mediator to map from that external interface to whatever the database adapter is offering:

The mapping in the transformation is fairly simple – because of the very adequate conversion performed by the database adapter from the database types of ORDER_TABLE_T and ORDER_T to their counterpart XSD types:

After deployment of the composite OrderService, we can test it – with the same input as the PL/SQL test of the ORDER_SERVICE_IMPL package:

At this point both the domain services have been created and deployed. We are ready to create the composite CustomerOrderService. Note that the hardest work has been done by now, inside the PL/SQL package.

Implementation of the Composite CustomerOrderService

BPEL’s core strength is orchestrating web service calls. It is the perfect tool in many occasions to create a composite service. The CustomerOrderService is such a composite service – a service that uses multiple other services for its implementation. This architecture view tells the story of the CustomerOrderService:

This service invokes the CustomerService (in the CRM Domain) as well as the OrderService (in the SALES domain). BPEL is used to implement the composite service. This overview of the SCA Composite for the CustomerOrderService says it all:

WebService References are created in the composite for each of the two domain level services that need to be invoked. A BPEL component is added and wired to these two references. The CustomerOrderService is exposed as service and wired to the BPEL component. In go a location and out comes a list of orders:

The BPEL process itself is easily described. Step one – the first scope – consists of invoking the CustomerService to retrieve a list of customer identifiers for all customers located at the designated location. The second step – scope number two – entails calling the OrderService with this list of identifiers in order to retrieve the sought after order details.

A global BPEL variable is used to store the list of identifiers and carry over this list from the first to the second scope. The second scope contains two Transform activities – one to map the customer identifiers to the input variable for the OrderService and the second one to map the output from the OrderService call (the order records) to the output variable of the BPEL process.

Let us do a simple test: find all the open orders for customers located in Zoetermeer:

The message flow trace makes it clear what happened during the execution of the CustomerOrderService:

A BPEL process is instantiated. It invokes the CustomerService – that in turn makes a single call to a database adapter service (for the query against CUSTOMERS). Next the BPEL process goes on to invoke the OrderService (just a single invocation). This composite too invokes a database adapter service (for the query against the ORDERS table). This is also a single call – a single round trip from SOA Suite run time to the database.

We have retrieved records based on a join across the domains CRM and SALES – without actually creating a dependency between the two databases involved – and without sacrificing [a lot] in terms of elegance, performance and scalability.

Resources

Download the JDeveloper 11.1.1.7 (11gR1 PS6) workspace with all the sources discussed in this article: CrossServiceJoin,zip.

Here is what Oracle says about it:

I had not read this description prior to watching (or experiencing) the first lesson; but it proved true. I was very pleasantly surprised. The ADF Academy is a multi media experience that uses every trick in the book – or every option for interaction, illustration, explanation and demonstration I could think of.

Different voices, music, code samples, cartoons, demonstrations, bits of video.

I frequently attend webinars – and they typically very quickly get boring and I have a hard time focusing and staying engaged. The voice drones on, the graphics are power point slides, the story is too high level (or far too detailed). There are many pitfalls for such on-line trainings. I still like my books very much – as they allow me my own pace and to some extent imagination as well. But of course when reading a book, I need to work through samples to bring things to life.

It seems that ADF Academy has adopted something close to the style of perhaps my favorite range of text books: the Head First [Java|Design Patterns|..] series. The Head First books also use every option in terms of rephrasing and visualizing the concepts under scrutiny. Cartoons are frequently used to clarify and underline the important messages. Here is one of the pages in the lesson on ADF Mobile application Development:

At first glance, these cartoons may seem a little childish perhaps. But it is my personal experience that they make learning fun. It helps to refocus – also to break through what otherwise might have been a monotonous experience.

Note that it is not just cartoons. There is live demo:

and source code:

overviews of what the next section will teach us:

architecture overviews:

step by step code clarification (both through audio and visuals):

and self test quizzes:

An additional bonus in the lesson is the appearance of several key people whose names you may know from forums or blogs – now suddenly doing bits and pieces of live action explanation. Here is Chris Muir making a contribution from Perth, Australia:

All in all I think that this way of presenting information and teaching me about using special aspects of ADF is a great addition to all existing resources. It is fun to watch, entertaining, has a good structure, explains both the high level overview as well as the fine grained technical details. In any review I like to find fault with whatever I am reviewing, just like a tester is out to uncover bugs. However, I am really happy with the ADF Academy. I am looking forward to additional lessons. Well done ADF-team!

Developing Applications with ADF Mobile is available here.

Take to opportunity and learn to work with a great framework to develop mobile applications for iOS and Adroid.

Also keep an eye on technology.amis.nl for more ADF Mobile related content.

• you don’t know beforehand what attribute or column will change, or
• you don’t want to replicate this “Model logic” in the View layer (e.g. because you want to adhere to the Model-View-Controller pattern), or
• components are scattered across Taskflows (in which case you cannot use the declarative support and the programmatic approach is suddenly very hard)?

Fortunately, ADF has a solution: Automatic Partial Page Rendering (or Auto PPR). If you have used ADF with Business Components, you might have seen or used it already, but it is less obvious that you can also use it with ordinary Beans or Bean DataControls.

Using Business Components

With ADF Business Components this is almost too easy. The ADF BC DataControl automatically maintains per Attribute a list of View Components that use/display it. It also keeps track of changes in attributes. The only thing you need to do is tell it that it should use this information for Auto PPR, using one simple property: ChangeEventPolicy in the PageDef. You can set it on an attributeValues binding. In that case only changes from that particular attribute will be propagated automatically, for example:

[xml]
<attributeValues IterBinding=”EmployeesView1Iterator” id=”FullName” ChangeEventPolicy=”ppr”>
<AttrNames>
<Item Value=”FullName”/>
</AttrNames>
</attributeValues>
[/xml]

Or you can set it on the iterator binding, in which case it is enabled for all attributes of this iterator:

[xml]
<iterator Binds=”EmployeesView1″ RangeSize=”25″ DataControl=”AppModuleDataControl”
id=”EmployeesView1Iterator” ChangeEventPolicy=”ppr”/>
[/xml]

Using ordinary Beans or Bean DataControls

As explained above, ADF Business Components automatically maintains a list of consuming Components and keeps track of changes, but your Bean – being a Plain Old Java Object – obviously does not. Suppose we want to create the following “application”:

Whenever someone enters a first name or a last name, the full name updates. When the full name updates (whenever someone enters something in any of the name fields) the bottom label also updates to reflect the new full name. This would be very easy using partialTriggers if it weren’t for the fact that the name fields are in a separate Taskflow. This Taskflow is included in a region on the page that contains the “Enter a bio for <FullName>” label.

This example is obviously made up for this blogpost, but situations like this are quite common. It is not hard to imagine that you would want to reuse the logic to enter a person’s name, but also use the person’s full name in other parts of the application. You don’t know (in the context of the “Name details” Taskflow) all the components in other parts of the application that depend on the full name. In fact you don’t want to know, because that would rather defeat the purpose of the Taskflow (i.e. reuse and modularization). So the programmatic approach is also not an option.

The basis of the implementation is a DataControl based on the following bean (not yet including the Auto PPR logic):

[java]
public class EmployeeBean {
private String firstName, lastName, fullName;

public void setFirstName(String firstName) {
this.firstName = firstName;
refreshFullName();
}

public String getFirstName() {
return firstName;
}

public void setLastName(String lastName) {
this.lastName = lastName;
refreshFullName();
}

public String getLastName() {
return lastName;
}

public void setFullName(String fullName) {
this.fullName = fullName;
}

public String getFullName() {
return fullName;
}

private void refreshFullName() {
String first = firstName == null ? “” : firstName;
String fullName = lastName == null ? first : first + ” ” + lastName;
setFullName(fullName);
}
}
[/java]

Now, we need to do two things:

1. Whenever getFullName() gets called we want to remember the consumer (JSF Component) that requested it.
2. Whenever setFullName(String) gets called we want to do a partial update of all the components that we remembered from step 1.

This sounds easy and it also turns out to be easy. We can reuse the part of the ADF framework that does this for ADF BC. Using a small utility class (AutoPPRSupport.java) I created for this occasion, the only thing we have to do is add a new member to our bean…

[java]
private final AutoPPRSupport autoPPRSupport = new AutoPPRSupport();
[/java]

… and change the getFullName() en setFullName(String) as follows…

[java]
public void setFullName(String fullName) {
this.fullName = fullName;
autoPPRSupport.notifyConsumers(“fullName”, fullName);
}

public String getFullName() {
autoPPRSupport.rememberConsumerForAttribute(“fullName”);
return fullName;
}
[/java]

… and that’s it! Now, whenever you use the fullName attribute in a JSF Component, it will automatically update when needed. Download the example.

In this particular case we don’t have any rows, so we don’t have to tell the framework which specific row was updated. I leave it as an exercise for the reader to work that one out (hint: using primary keys).

(This post also appeared on my personal blog: http://www.adfplus.com.)

The customer had a table where users could multi-select via an extra column with checkboxes. Header of that column also contained a checkbox to select or deselect everything at once. For example:

It was implemented using autoSubmit and partialTriggers. Due to the roundtrip to the server the response time was low when having a lot of rows. To speed it up, I was asked to look if (de)selecting all rows could be done on the client.

Never having worked with that part of ADF yet, I started searching and quickly found the Oracle documentation, but actual examples to clarify some topics.. hmmm not so much.
The use case is quite specific but I thought it would still be nice to blog about it to be at least an example of some of the client-side functionality for other people in need.

The column

Let’s start with the column:
[xml highlight="4,5,6,9"]
<af:table var=”row” id=”tab” ..>
<af:column id=”checkboxCol” width=”25″ align=”center” displayIndex=”0″>
<f:facet name=”header”>
<af:selectBooleanCheckbox id=”checkboxHeader” value=”#{bindings.selectEmployeeValue.inputValue}”>
<af:clientListener method=”selectRows” type=”click”/>
<af:clientAttribute name=”tableLocator” value=”::tab”/>
<af:clientAttribute name=”checkboxLocator” value=”:checkbox”/>
</af:selectBooleanCheckbox>
</f:facet>
<af:selectBooleanCheckbox id=”checkbox” value=”#{row.selected}” clientComponent=”true”/>
</af:column>
.
.
</af:table>
[/xml]

When the user clicks on the checkbox in the header some javascript code will have to loop through the rows to change the checkboxes of each row.

For this I add a client listener to the header checkbox which will trigger on a click and calls some javascript method which in my case I called “selectRows”.
To make the javascript method generic I add the table and checkbox identifiers as attributes of the checkbox.
As identifiers I use the locators of the table and row checkboxes relative to the header checkbox; when we look at the javascript it will become clear why.
Last but not least, all row checkboxes get a clientComponent=”true” to make sure the client framework can access it.

The ADF client-side architecture wraps around the DOM model and can create javascript objects for faces components.
Javascript objects are created in multiple cases, among others when a component has a clientListener or the property clientComponent=”true”.
When looking for API information you can easily guess which API you need to search for. When you have an exposed RichSelectBooleanCheckbox component its javascript equivalent will be an AdfRichSelectBooleanCheckbox.

The JavaScript

Defining the client listener is comparable to other server listeners like an action listener.
When you add i.e. an action listener you will need an listener method with an ActionEvent parameter.
A client listener needs a javascript method with an event parameter as well:
[javascript]
function selectRows(event) {

/* TODO
retrieve the header checkbox from the event
retrieve attributes
find the table
for each row, find the checkbox to set value of
while(..){
..
}
*/
}
[/javascript]

The clientListener is added to the header checkbox making this checkbox the source of the event.
Via the event we can retrieve this AdfRichSelectBooleanCheckbox:
[javascript]
function selectRows(event) {

var checkbox=event.getSource();

/* TODO
retrieve attributes
find the table
for each row, find the checkbox to set value of
while(..){
..
}
*/
}
[/javascript]

Once we have our checkbox object we can retrieve its attributes:
[javascript]
function selectRows(event) {

var checkbox=event.getSource();

var checkboxLocator=checkbox.getProperty(“checkboxLocator”);
var tableLocator=checkbox.getProperty(“tableLocator”);

/* TODO
find the table
for each row, find the checkbox to set value of
while(..){
..
}
*/
}
[/javascript]

The similarities in the client-side architecture are again convenient. The javascript objects have a findComponent method to search from a relative path. The root has a findComponentByAbsoluteId method to search for an object starting from the root.

The tableListener attribute contains the relative path to the table, reasoning from position of the header checkbox. This way we can do a findComponent on the header checkbox to easily get the AdfRichTable object:
[javascript]
function selectRows(event) {

var checkbox=event.getSource();

var checkboxLocator=checkbox.getProperty(“checkboxLocator”);
var tableLocator=checkbox.getProperty(“tableLocator”);

var table=checkbox.findComponent(tableLocator);

/* TODO
for each row, find the checkbox to set value of
while(..){
..
}
*/
}
[/javascript]

So far so good, and nothing that can’t already be found when googling. But trying to reach the checkboxes of the rows was tricky.
To figure it out I started by looking at the HTML source of the ADF table with the checkbox of the first row:
[xml]
<td style=”width:25px” align=”center” nowrap=”" class=”xxv”>
<span id=”tab:0:checkbox” class=”x1v”>
<span class=”x2e”>
<span class=”xgx”>
<input id=”tab:0:checkbox::content” …>
</span>
</span>
</span>
</td>
[/xml]

The ID in the span made me do a couple of first attempts with the findComponent of the header checkbox like
[javascript]checkbox.findComponent(“::tab["+rowNumber+"]:checkbox”);[/javascript]

Though this works the first time you open the page, it can break in certain situations.
Problem is that the first row not always gets 0 as a stamp etc. When you for instance have a master-form detail-table layout and navigate to the second master row, your detail row stamp continues to count from the last stamp of the first master row.
But also actions like fetching and refreshing changes the stamps.

After some more searching I found out that finding components by locator should solve the stamp issue.
This allows me to use [0] to address the first row and ADF will look up to which actual stamp this translates at that moment.
It resulted in some next attempts like
[javascript]checkbox.findComponentByLocator(“::tab["+rowNumber+"]:checkbox”);[/javascript]

It turned out the table part of the expression was not correct yet.
Some more digging in the APIs to see how I could figure out the locator of the table made me stumble upon AdfUIComponent.getAbsoluteLocator() and a note in AdfUIComponent.findComponentByLocator that there was a method called AdfPage.findComponentByAbsoluteLocator().

Tying those last knots together finally gave a successful result:
[javascript]
function selectRows(event) {

var checkbox=event.getSource();

var checkboxLocator=checkbox.getProperty(“checkboxLocator”);
var tableLocator=checkbox.getProperty(“tableLocator”);

var table=checkbox.findComponent(tableLocator);

var nbRows=parseInt(table.getRows());
var tableAbsLocator=table.getAbsoluteLocator();

while(nbRows–){
var rowCheckbox=AdfPage.PAGE.findComponentByAbsoluteLocator(tableAbsLocator+”["+nbRows+"]“+checkboxLocator);
if(checkbox.getValue()!=rowCheckbox.getValue()){
rowCheckbox.setValue(checkbox.getValue());
}
}
}
[/javascript]

I have created a quick little project for this.
I immediately admit it is quite ugly as I put the boolean for the checkboxes in my model, but it is just to show the client side selection.

Note

This solution only checks or unchecks all fetched rows. As non fetched rows are not in the HTML tree yet it is not possible to check them.
In my use case the query results were maxed to a certain amount which was also used as fetch size to solve this issue.

Resources

Oracle white paper – ADF Design Fundamentals Using JavaScript in ADF Faces Rich Client Application

Oracle Web User Interface Developer’s Guide (11.1.1.5) – H3 Using ADF Faces Architecture

Oracle Web User Interface Developer’s Guide (11.1.1.5) – H5 Handling Events

Oracle JavaScript API Reference (11.1.1) - http://docs.oracle.com/cd/E21043_01/apirefs.1111/e12046/overview-summary.html

Little example project - ClientSideMultiSelect.zip

First of all, a must have is Macroplants iExporer. This will let you browse any connected iDevice, including some of the data that gets stored within the apps on the device. Using this tool to have a look at the apps your have built will show you what data is easily accessible for anyone who can hookup the device to their computer. (Spoiler: Even locked and password protected devices can be browsed through iExplorer). Download it here and use it to your advantage.

A lot of these security ‘issues’ have everything to do with knowing the platform you are building for. Take for example the backgrounding issue mentioned earlier. As it turns out, iOS will take a screenshot of your app every time it is sent to the background. This screenshot is later used to make your iPhone look a bit quicker when you open your app again, while the app is loaded, iOS will show the screenshot that was taken earlier. If you ever had an app taking a moment before responding again, you were probably pushing buttons on a screenshot. The issue here is that any private data that is on the screen will be stored when the screenshot is taken, these are easily found using iExplorer (or any other application with the same kind of access).

iExplorer – Screenshot Location

Luckily for us, this is fairly easy to anticipate and damage can be prevented with only a few lines of code. In your app delegate you can find the following functions:

AppDelegate Functions to control backgrounding

Using  – (void)applicationDidEnterBackground:(UIApplication *)application  we can ensure to hide any sensitive data from being stored in the screenshot. The most common ways to do this are to show your Default.png image on top of anything else. This way any screenshot will just be a copy of your startup/loading screen, and as an added bonus, when someone starts the app agian they will see a familiar screen.

AppDelegate Functions – Solution

Another way of doing things is to send a notification using NSNotificationCenter. You can then just add an observer for every view where you might want to hide some data. In the specific view you can decide to just hide certain fields or the whole screen.

This example as well as many others is also found in iGoat, an application that will help you to learn a bit more about iOS application security leaks and how to prevent them. I can recommend everyone to check out and download iGoat here.

ADF DVT Pie Graph – Introduction

The pie chart is one of the most widely used statistical chart for simple representation of the division of data amongst different groups.
It is a simple effective way to see in an instant for example the ratio between country populations when looking at them as portions of the total population.

ADF DVT provides smooth looking configurable Pie Graph components in slightly different flavours:
- the pie, a single pie view. For example one pie for the population per country
- the multi pie, a view with mutliple pies. For example per continent a pie with the population per country of that continent
- the pie-bar, For example a pie with the population per continent, with zoom on population per country of that continent
- ring graph
- ring-bar graph

For this blog I will leave out the ring flavours, as they are quite similar.

These ADF components can either be based on some simpel tabular data (via a bean for example) or they can be data bound.
In the latter case, just like other components, you can drag a group from the data control on to your page and choose “graph” for the context menu.

Dragging a pie graph on the page will result in a couple of things.

1. In design view we see the following:

This is just a dummy pie and is only usefull for when you are configuring titles etc.

2. Then we have the source view, which is quite readable and gives us a hint of how the graph is build and what we could change:

We see the graph itself also contains of subelements, like seriesSet. These can also be clearly seen in the structure pane:

3. and PageDef:

Here we can see series and groups. This structure is used for more than just the PIE graph component. In case of the pie graph series are the slices and groups are the grouping data.

So in this example we have a pie with the profit per country.

ADF DVT Pie Graph – Properties

Looking at the properties there are a lot of properties that you are already familiar with from other components, like id, rendered and value property, inlineStyle, styleClass, partialSubmit, bindings changeListeners etc.

Lets focus on the new properties for graphs:

We see properties like “3D effect” to change a flat pie into the 3D pie shown in the design view screenshot above,properties for animation, titles of different parts of the graph, click listeners, image format (HTML5, Flash, PNG). Each of the subelements of a graph (select via source or structure pane is easiest) also holds properties.

For example, a sliceLabel can be given a numberFormat, resulting in the following:

Pies can be approached as a table, where a slice then must be looked at as a row. With clickListener and partialTrigger properties we can even create a master-detail with graphs:

ADF DVT Pie Graph – Example

In this example we are going to play around with different pie graph flavours, properties and create a master-detail.

First please download the this zip, containing a base workspace and some ddl files to set up the DB: AdfSpeedDate_PieGraph (JDev 11.1.1.6)

Database

Open workspace DvtPieGraph.jws. Check the settings of the database connection within the application and correct if needed to point to the database for the hand-on session.
Run the install.sql against the database connection.

Model Layer

Workspace DvtPieGraph.jws contains of two projects, Model and ViewController. Model holds an empty Application module and ViewController an empty page to put the DVT components on.

First step we need to take is filling the data control with usefull information. We want to create a page with profit information per country and per restaurant.

1. Create a custom ViewObject CountryFinancesVO.

The View object needs to contain the revenue and cost information aggregated per country:

SELECT countries.id   country_id
,      countries.name country_name
,      SUM(revenue)   country_revenue
,      SUM(costs)     country_costs
FROM   dve_countries    countries
,      dve_restaurants  restaurants
,      dve_revenue      revenue
WHERE  countries.id   = restaurants.country_id
AND    restaurants.id = revenue.restaurant_id
GROUP BY countries.id
       , countries.name

While creating, don’t add the view Object to the Application Module yet.

2. Add a transient NUMBER attribute to the view object that calculates the countryProfit (revenue-costs).
3. Create a view object RestaurantFinancesVO, to represent the revenue and cost information per restaurant:

SELECT restaurants.id           restaurant_id
,      restaurants.country_id   country_id
,      restaurants.name         restaurant_name
,      SUM(revenue)             restaurant_revenue
,      SUM(costs)               restaurant_costs
FROM   dve_restaurants  restaurants
,      dve_revenue      revenue
WHERE  restaurants.id = revenue.restaurant_id
GROUP BY restaurants.id
       , restaurants.name
       , restaurants.country_id

4. Add a transient NUMBER attribute to the view object that calculates the restaurantProfit.
5. Create a View link between the two VOs, from Countries to Restaurants, to represent the Master-Detail relationship between them.

When creating, add this Link to the Application Module.

6. Open the data model of the Application Module and give the created Master-Detail better names, for example CountryFinances and RestaurantFinancesPerCountry.

We are now ready to start with our first graph!

Let’s make some pies

Simple Pie: Profit per Country

In this exercise we are going to make a pie graph showing the profit per country.

1. Start by opening the .jsff file already available in the ViewController project.

2. Open the data control and select the CountryFinances group. Drag this group on the page. This will open the option context menu. Choose “Graph…”

3. A Component gallery will open with all kinds of graphs to choose from. Go to the Pie subgallery and choose a single pie and the second quick start layout.

4. The next dialog will open to configure the graph. We would like to make a graph on the country profit and see which country is responsible for how much percent of the total profit. See if you can find out which attribute needs to be defined where. Please check the checkbox “Set current row for master-detail”. This option will be for the next exercise. Press OK to place the component on the page.

Take a quick look at the source of the page and at the pagedef to see what is generated for this component.

5. Right-click on the pie. A context menu should open with all kinds of placeholders which are either checked or not. We chose a start layout with a bit too much fluff, make sure the footnote and subtitle are not rendered no more.

6. Adjust the title to “Profit per Country” and Legend title to “Country Legend”. Click on parts of the component and look at the property inspector. How does the component look in the structure pane? 

7. Go to the properties of the whole graph. Walk a bit through the properties and adjust the graph to a 3d view.

Run the page to see the pie.

8. Hoover over the slices and see how the info about profit is shown. Notice how the amount is scaled to for example 60K? This is a setting that can be altered. You can even add your own number format. Try to format it such that the amount shows a currency sign. 

Re-run your page to see if it worked!

Master-Detail Pie: Profit per Restaurant of a Country

In the first exercise we had checked the option “Set current row for master-detail” on the CountryProfit graph. Time to find out what this option does.

1. Go to the property inspector of the graph and find the clickListener to see a value filled in.

The option will prepare the first graph act like a master just like in a master-detail screen with tables. Only difference is that instead of master rows we now have master slices.

2. In the model we already prepared for a master-detail, Country-Restaurant, so let’s try to make a detail graph showing the profit sliced per restaurant. Place a horizontal group layout around the first graph.

3. In the Data Control panel, drag the group below CountryFinances, RestaurantFinancesPerCountry, on the page next to the Country graph. Choose again a pie graph and try a different start layout just because we can. 

4. Clean the component up a little by giving it the title “Profit per Restaurant” and try to figure out how to make sure the subtitle shows “in ” plus the country name of the current selected slice of the Country graph. 

5. We already saw the parent is prepared to listen to a click event, but if you run the page you will see the child is not refreshed when the parent is clicked. Make sure the restaurant graph refreshes whenever a slice of the parent is clicked. 

Run the page and click to see a nice master-detail page with pies.

Multi-pie: Costs and Revenue per Restaurant

One pie at the time should be piece of cake by now. Time to try the multi-pie. Make sure there is another horizontal group layout under the first one.

1. Drag RestaurantFinancesPerCountry on the page in this new group layout but this time choose Multiple Pie. Choose a start layout you like and hit OK.

2. So far we looked at profit, but we would like to see a breakdown in costs and revenue. Try to figure out how to make the component show one pie for the restaurant costs showing for which percentage of the costs each restaurant is responsible and one similar pie for the revenue. Two pies Costs and Revenue, showing Restaurant slices..

3. It should look like this:

4. Make sure the graph refreshes when there is a parent slice clicked and run the page to play around with your first multi-pie graph.

Colored pies: cost/revenue pies

One last time: drag RestaurantFinancesPerCountry at the right of your multi-pie, and choose again a multi-pie. This time let’s see if you are also able to make a pie per restaurant showing the ratio between costs and revenue. So restaurant pies with a cost slice and revenue slice..

1. If you run the page you will see pies being half blue half red. You have to really look at the legend or slice label to see which of the slices are the costs and which are the revenue.

I think it would be clearer for the customer if the costs slice would be red and the revenue would be green. Select the graph and take a look at the structure pane.

2. If the pieGraph does not show a seriesSet yet, stand on the graph and choose ‘insert inside dvt:pieGraph..’ and select dvt:seriesSet.

Series in ADF represent slices. A seriesSet allows you to set properties for all slices. In our case we want to set two times a property for a specific slice though, so we need a dvt:series within the dvt:seriesSet. Make sure the dvt:seriesSet contains two dvt:series.

3. Select a dvt:series and look at the property inspector. Find the property color and click on the arrow icon at the end to edit. A color picker will show to pick a color from. `

Set the colors and run the page.

ADF DVT Pie Graph – Resources

Download the JDeveloper 11gR1 11.1.1.6 Start Application - DvtPieGraph.zip and complete application  -  DvtPieGraph_complete.zip

Oracle documentation of graphs - http://docs.oracle.com/cd/E25178_01/web.1111/b31973/dv_graph.htm#ADFUI459

Oracle Rich Client Live Demo - http://jdevadf.oracle.com/adf-richclient-demo/faces/feature