Xml and More

How to Avoid Deadlocks

2012-01-29T16:17:00.000-08:00

Deadlock can be illustrated by the classic dining philosophers problem^[1].

In an operating system, a deadlock^[2] is a situation which occurs when a process enters a waiting state because a resource requested by it is being held by another waiting process, which in turn is waiting for another resource. If a process is unable to change its state indefinitely because the resources requested by it are being used by other waiting process, then the system is said to be in a deadlock.

In Java programming, deadlocks may manifest themselves where multiple threads wait forever due to a cyclic locking dependency. For example, when thread A holds lock L and tries to acquire lock M, but at the same time thread B holds M and tries to acquire L, both threads will wait forever. Just as threads can deadlock when they are each waiting for a lock that the other holds and will not release, they can also deadlock when waiting for resources. Comparing to deadlock, starvation and livelock are much less common a problem, but are still problems that every designer of concurrent software is likely to encounter. Java applications do not recover from deadlock, so it is worthwhile to ensure that your design precludes the conditions that could cause it^[6].

In this article, we will discuss some threading best practices to avoid deadlocks.

Necessary Conditions

A deadlock situation can arise only if all of the following conditions hold simultaneously in a system:^[3]

Mutual Exclusion: At least, one resource must be non-shareable. Only one process can use the resource at any given instant of time.
Hold and Wait: A process is currently holding at least one resource and requesting additional resources which are being held by other processes.
No Preemption: The operation system can de-allocate resources once they have been allocated. They must released by the holding process voluntarily.
Circular Wait: A process waiting for a resource which is being held by another process, which in turn is waiting for another process to release a resource.

Unfulfillment of any of these conditions is enough to preclude a deadlock from occurring.

How to Avoid Deadlocks

Never cede control to the client within a synchronized method or block^[4]

Invoking an alien method with a lock held is asking for liveness trouble. The alien method might acquire other locks (risking deadlock) or block for an unexpectedly long time, stalling other threads that need the lock you hold.

In other words, inside a synchronized region, do not invoke a method that is designed to be overridden, or one provided by a client in the form of a function object (i.e., object references used to implement the Strategy pattern). The class has no knowledge of what the alien method does and has no control over it. If you do call an alien method from within a synchronized region, you open the opportunities of deadlocks by allowing the following conditions to hold:

Hold and Wait
Circular Wait

Because you call the alien method from a shynchronized region, it holds a lock. If this alien method is overriden and it engages the services of another thread to do the deed, Hold and Wait condition will be established. Given another counterpart of Hold-and-Wait, it can possibly form a Circular Wait condition.

Calling a method with no locks held is called an open call^[6], and classes that rely on open calls are more well-behaved and composable than classes that make calls with locks held.

More generally, try to limit the amount of work that you do from within synchronized regions. When you are designing a mutable class, think about whether it should do its own synchronization. Synchronize your class internally only if there is a good reason to do so, and document your decision clearly.

Ensure that resources are always acquired in some well-defined order^[7]

Deadlocks can be avoided by assigning a partial order to the resources, and establishing the convention that all resources will be requested in order, and released in reverse order, and that no two resources unrelated by order will ever be used by a single unit of work at the same time. This solution to the dining philosophers problem was originally proposed by Dijkstra.

There are different approaches to enforce a partial order to the resources:

If resources are static and known in advanced
- Just stick to a programming policy (i.e., all programmers apply the policy of acquiring the locks in some well-defined order)
- Provide a method that combines acquisition and release of the multiple locks in the correct way (see here for an example)
If resources are not known in advanced or acquired dynamically
- We have to explicitly define some way of ordering them. For example,
  - If locking will only exist for the lifetime of the application
    - We can use the identity hash code (System.identityHashCode(r)) of the two objects.
    - In the rare case that two objects have the same hash code, we must use an arbitrary means of ordering the lock acquisitions, and this reintroduces the possibility of deadlock. To prevent inconsistent lock ordering in this case, a third tie breaking lock can be used^[6].

Removing the mutual exclusion condition

Removing the mutual exclusion condition means that no process will have exclusive access to a resource. This proves impossible for resources that cannot be spooled. But even with spooled resources, deadlock could still occur. Algorithms that avoid mutual exclusion are called non-blocking synchronization algorithms.

For example, optimistic concurrency control^[9]uses a pair of consistency markers in the data structure. Processes reading the data structure first read one consistency marker, then read the relevant data into an internal buffer, then read the other marker, and then compare the markers. The data is consistent if the two markers are identical. Markers may be non-identical when the read is interrupted by another process updating the data structure. In such a case, the process discards the data in the internal buffer and tries again.

Finally, immutability is great for multi-threading. Instances of immutable class appear constant. Therefore, no external synchronization is necessary. Examples include String, Long, and BigInteger.

Using timed lock acquisition to acquire multiple locks^[6]

Another technique for detecting and recovering from deadlocks is to use the timed tryLock feature of the explicit Lock classes instead of intrinsic locking.

If a lock acquisition times out, you can release the locks, back off and wait for a while, and try again, possibly clearing the deadlock condition and allowing the program to recover. However, this technique works only when the two locks are acquired together; if multiple locks are acquired due to the nesting of method calls, you cannot just release the outer lock, even if you know you hold it.

Conclusion

We conclude this article by quoting Goetz et al.^[6]:

Like many other concurrency hazards, deadlocks rarely manifest themselves immediately. The fact that a class has a potential deadlock doesn’t mean that it ever will deadlock, just that it can. When deadlocks do manifest themselves, it is often at the worst possible time—under heavy production load.

References

Dining philosophers problem
Deadlock
Advanced Synchronization in Java Threads by Scott Oaks and Henry Wong
Effective Java by Joshua Block
Threading Best Practices
Java Concurrency in Practice by Brian Goetz, Tim Peierls, Joshua Bloch, Joseph Bowbeer, David Holmes and Doug Lea
Deadlock Tutorial
The Java Tutorial (Concurrency)
Optimistic concurrency control
Concurrency: State Models & Java Programs (2nd Edition), by Jeff Magee and Jeff Kramer.
Java Concurrent Animated

Volatile Keyword in Java

2012-01-22T20:45:00.000-08:00

Multithreading is one of the most important software technologies for boosting the performance and scalability of all types of software. However, it comes at a prise—complexity. The pain of concurrent programming can be alleviated by a framework like Hadoop. However, as a Java programmer using threads, you need to deal with three interwined issues:

Atomicity
Visibility
Ordering

Working Memory

Java Memory Model defines an abstract relation between threads and main memory. Every thread is defined to have a working memory (an abstraction of caches and registers) in which to store values. The model guarantees a few properties surrounding the interactions of instruction sequences corresponding to methods and memory cells corresponding to fields. Most rules are phrased in terms of when values must be transferred between the main memory and per-thread working memory.

Common variables such as instance fields, static fields and array elements in heap memory can be shared between threads. At any time, these variables can be kept in one of the following locations:

Register
L1-L3 caches
Main memory
Hard disk (passivation and activation of Java Beans; paging or swapping)

When multiple threads are all running unsynchronized code that reads and writes common variables, then:

Arbitrary interleavings
Atomicity failures
Race conditions
Visibility failures

may result in execution patterns.

Atomicity

The language specification guarantees that reading or writing a single variable is atomic unless the variable is of type long or double. This includes fields serving as references to other objects. In other words, this implies that every thread accessing a field of any type except long or double will read its current value before continuing, instead of (potentially) using a cached value. This atomicity guarantee can be extended to longs or doubles, if you declare them volatile. We'll discuss this more later.

Visibility

Visibility discusses under what conditions the effects of one thread are visible to another. The effects of interest here are writes to fields, as seen via reads of those fields. While the atomicity guarantee ensures that a thread will not see a random value when reading atomic data, it does not gurantee that a value written by one thread will be visible to another:

Synchronization is required for reliable communication between threads as well as for mutual exclusion^[8]

If a variable is declared volatile, this signals that the variable will be accessed by multiple threads, and also gives visibility guarantees.

Ordering

Ordering describes under what conditions the effects of operations can appear out of order to any given thread. The main ordering issues surround reads and writes associated with sequences of assignment statements.

If a program has no data races, then all executions of the program will appear to be sequentially consistent. If JLS were to use sequential consistency as its memory model, many of the compiler and processor optimizations would be illegal. For example, JLS allows the following statements to be reordered:

This provides essential flexibility for compilers and machines. Exploitation of such opportunities (via pipelined superscalar CPUs, multilevel caches, load/store balancing, interprocedural register allocation, and so on) is responsible for a significant amount of the massive improvements in execution speed seen in computing over the past decade.

In other words, not only may concurrent executions be interleaved, but they may also be reordered and otherwise manipulated in an optimized form that bears little resemblance to their source code. As compiler and run-time technology matures and multiprocessors become more prevalent, such phenomena become more common. They can lead to surprising results for programmers with backgrounds in sequential programming who have never been exposed to the underlying execution properties of allegedly sequential code. This can be the source of subtle concurrent programming errors. In almost all cases, there is an obvious, simple way to avoid contemplation of all the complexities arising in concurrent programs due to optimized execution mechanics: Use synchronization. There are multiple ways to achieve synchronization. Below we'll disucusss using volatile keyword in Java for limited cases.

Volatile

In terms of atomicity, visibility, and ordering, declaring a field as volatile is nearly identical in effect to using a little fully synchronized class protecting only that field via get/set methods, as in:

final class VFloat { 
  private float value; 

  final synchronized void set(float f) { value = f; } 
  final synchronized float get() { return value; } 
}

This may invovle low-level memory barrier machine instructions to keep value representations in synch across threads. However, it involves no locking. In the following sections, we will discuss what're the good occasions for you to use volatile and what're the dangers of misusing it.

When to Use Volatile

Declaring fields as volatile can be useful when you do not need locking for any other reason, yet values must be accurately accessible across multiple threads. This may occur when^[5]:

The field need not obey any invariants with respect to others.
Writes to the field do not depend on its current value.
No thread ever writes an illegal value with respect to intended semantics.
The actions of readers do not depend on values of other non-volatile fields.

Below we provide some examples for such usages:

Use volatile in DCL

Double-checked locking (DCL) is OK as of Java 5 provided that you make the instance reference volatile.

// Works with acquire/release semantics for volatile in Java 5
class Foo {
  private volatile Helper helper = null;
  public Helper getHelper() {
  if (helper == null) {
    synchronized(this) {
      if (helper == null)
        helper = new Helper();
      }
    }
    return helper;
  }
}

In Java 5, JLS ensures that the unsycnrhonized volatile read must happen after the write has taken place, and the reading thread will see the correct values of all fields on Helper.

Use volatile in Control Flag

// Cooperative thread termination with a volatile field
public class StopThread {
    private static volatile boolean stopRequested;

    public static void main(String[] args)
            throws InterruptedException {
        Thread backgroundThread = new Thread(new Runnable() {
            public void run() {
                int i = 0;
                while (!stopRequested)
                    i++;
            }
        });
        backgroundThread.start();

        TimeUnit.SECONDS.sleep(1);
        stopRequested = true;
    }
}

Volatile declarations on control flags are needed to ensure that result flag values are visible across threads.

Dangers of Using volatile Keyword

Composite operations such as the "++" operation on volatile variables both read and write the variable. So, they are not atomic.

// Need to add synchronized modifier to the volatile variable
// Once you’ve done that, you can and should remove the volatile modifier 
// from nextSeuqenceNumber[8].
private static int nextSequenceNubmer = 0;
public static synchronized int nextSeuqenceNumber() {
  return nextSequenceNumber++;
}

Ordering and visibility effects surround only the single access or update to the volatile field itself. Declaring a reference field as volatile does not ensure visibility of non-volatile fields that are accessed via this reference. Similarly, declaring an array field as volatile does not ensure visibility of its elements. In other words, it is unsafe to call arr[x] = y on an array (even if declared volatile) in one thread and then expect arr[x] to return y from another thread. See [1] for possible ways of fixing this issue.

Because no locking is involved, declaring fields as volatile is likely to be cheaper than using synchronization, or at least no more expensive. However, if volatile fields are accessed frequently inside methods, their use is likely to lead to slower performance than would locking the entire methods.

References

Volatile Arrays in Java
Dangers of Volatile Keyword
The Volatile Keyword in Java 5
The Volatile Keyword in Java
Synchronization and Thread Safety in Java
Double-Checked Locking and How to Fix it
Synchronization and Java Memory Model
Effective Java by Joshua Bloch
The Java Language Specification

Singleton Is Not as Simple as You Think

2012-01-21T16:43:00.000-08:00

As Gamma et al.^[1] put it, singleton ensures a class only has one instance,and provides a global point of access to it.

Typically, when modelling a system, business objects come out of the nouns defined within a use case statement^[2]. These Business Objects are acted upon by the external actors such as User of the System.

If you have only one file system or one window manager in the modelled system, these business objects are good candidates for singletons.

Creating and Destroying Objects

As a Java developer, one design consideration is related to create and destroy objects. Multiple design decisions need to be made on:

When and how to create objects
When and how to avoid creating them
How to ensure that objects are destroyed in a timely manner
How to manage any cleanup actions that must precede object destruction.

Using singleton, it can simplify the above design decisions. With it, a class can ensure that no other instance can be created (by instercepting requrests to create new objects), and it provides a way to access the instance.

However, as pointed out in this article, using singleton design pattern in a cluster environment is challenging.

Cluster

A computer cluster consists of a set of loosely connected computers that work together. If all nodes in the system use the same hardware, they are named cluster. If the nodes use different hardware, they are named grid. Technologies like cluster or grid have all aimed at allowing access to large amounts of computing power in a fully virtualized manner, by aggregating resources and offering a single system view. For example, Oracle RAC (Real Application Clusters) allows multiple computers to run Oracle RDBMS software simultaneously while accessing a single database, thus providing a clustered database.

When Fusion web application runs in a clustered environment, it must be possible for the node that the application is running on to fail, but to have it switched to a separate node without any impact on the user. The application server makes this possible by serializing the state that the application requires. If a node goes down, the user is moved to a different node, and the state is automatically recovered.

Similarly managed servers in a Oracle WebLogic domain may be grouped together in a cluster , running simultaneously and working together for increased scalability and reliability^[9]. In such a cluster, most resources and services are deployed identically to each managed server, enabling fail-over and load-balancing. Either active-active and active-passive failover patterns can be supported. For an active-active configuration, it requires an external load balancer to detect failure and automatically redirect requests. For an active-passive configuration, it provides a fully redundant instance of each node, which is only brought online when its associated primary node fails.

Multiple Singleton Implementations

Implementation 1

// Singleton with public final field
public class Singleton {
    public static final Singleton INSTANCE = new Singleton();
    private Singleton() { ... }
    public void doSomething() { ... }
}

As noted in [5], a privileged client can invoke the private constructor reflectively with the aid of the AccessibleObject.setAccessible method. If you need to defend against this attack, modify the constructor to make it throw an exception if it’s asked to create a second instance.

Implementation 2

// Singleton with static factory
public class Singleton {
    private static final Singleton INSTANCE = new Singleton();
    private Singleton() { ... }
    public static Singleton getinstance() { return INSTANCE ; }
    public void doSomething() { ... }
}

One advantage of the factory-method approach is that it gives you the flexibility to change your mind about whether the class should be a singleton without changing its API. The factory method returns the sole instance but could easily be modified to return, say, a unique instance for each thread that invokes it.

Implementation 3

// Enum singleton
public enum Singleton {
INSTANCE;
public void doSomething() { ... }
}

In [5], Joshua Bloch states that this approach is functionally equivalent to the public field approach (i.e., Implementation 1), except that it is more concise, provides the serialization machinery for free, and provides an ironclad guarantee against multiple instantiation, even in the face of sophisticated serialization or reflection attacks. In his opinion, a single-element enum type is the best way to implement a singleton.

Implementation 4

// Singleton implemented with lazy initialization
public class Singleton {
private static Singleton INSTANCE = null;
protected Singleton() {
   // Exists only to defeat instantiation.
}
public synchronized static Singleton getInstance() {
    if(INSTANCE == null) {
       INSTANCE = new Singleton();
    }
    return INSTANCE;
}
public void doSomething() { ... }
}

Because synchronization is very expensive performance-wise (synchronized methods can run up to 100 times slower than unsynchronized methods), we can introduce a performance enhancement that only synchronizes the singleton assignment in getInstance()^[4].

Implementation 5

// initialization-on-demand holder
public class Singleton {
private Singleton() { }
  private static class LazyHolder {
    public static final Singleton INSTANCE = new Singleton();
}
   public static Singleton getInstance() {
     return LazyHolder.INSTANCE;
   }
   public void doSomething() { ... }
}

The static class LazyHolder is only executed when the static method getInstance is invoked on the class Singleton, and the first time this happens the JVM will load and initialize the LazyHolder class. The initialization of the LazyHolder class results in static variable INSTANCE being initialized by executing the (private) constructor for the outer class Singleton.

Since the class initialization phase is guaranteed by the JLS to be serial, i.e., non-concurrent, no further synchronization is required in the static getInstance method during loading and initialization. And since the initialization phase writes the static variable INSTANCE in a serial operation, all subsequent concurrent invocations of the getInstance will return the same correctly initialized INSTANCE without incurring any additional synchronization overhead.

When is a Singleton not a Singleton?

In [3], Joshua Fox has shown that you can inadvertently allow more than one instance to be created under the following circumstances:

Multiple singletons in two or more virtual machines
Multiple singletons simultaneously loaded by different class loaders
Singleton classes destroyed by garbage collection, then reloaded
Purposely reloaded singleton classes
Multiple instances resulting from incorrect synchronization
Multiple singletons arising when someone has subclassed your singletons
Multiple singletons created by a factory specially asked to create multiple objects
Copies of a singleton object that has undergone serialization and deserialization
Multiple singletons caused by problems in a factory

As shown above, implementing singletons in Java is anything but simple. In [4], David Geary tells you how to test singleton classes by using JUnit and log4j.

Singleton in Cluster Environment

To support singletons in a cluster, you need to ask yourselves one question:

Is it "single" in the context of the running VM good enough

If your application requires an absolutely single instance in a cluster, you need to read [3] to see how to avoid the pitfalls of creating multiple singletons.

In a cluster environment, application state needs to be serialized and preserved across multiple nodes. To make a singleton class serializable, it is not sufficient merely to add implements Serializable to its declaration. To maintain the singleton guarantee, you must also provide a readResolve method. Otherwise, each deserialization of a serialized instance will result in the creation of a new instance. To prevent this, add the following readResolve method to the Singleton class:

// readResolve method to preserve singleton property
private Object readResolve() throws ObjectStreamExcetion {
// Return the one true INSTANCE and let the garbage collector take care of the cloned one
return INSTANCE;
}

In [7], it has discussed a case that uses singleton to cache some custom information from Database. This information is mostly read-only but gets refreshed when some particular event occurs. A question is asked:

When this singleton is deployed in a clustered environment, what is the best way to keep the cache in sync.

I'll just refer you to read [7] for possible approaches. However, in general, the approach is based on the object being cached.

If the object being cached is read-only or thread-safe, you simply make the field volatile.
If the cache object is mutable and not thread-safe, you have to make sure that any access to mutable fields in the object are synchronized.

References

Design Patterns: Elements of Reusable Object-Oriented Software by Gamma et al.
The Mysteries of Business Object
When is a Singleton not a Singleton?
Simply Singleton
Effective Java by Joshua Bloch
High-availability cluster
Singleton in Cluster environment
Initialization-on-demand holder idiom
Oracle Service Bus Clustering for Developers by Jeff Davies

Understanding Garbage Collection

2012-01-15T21:05:00.000-08:00

Every Java programmer will encounter

java.lang.OutOfMemoryError: Java heap space

sooner or later. The most often offered advices include:

Try increase the MaxPermSize first
Increase the PermSize to 256m

In this article, we will show what heap space, PermSize or MaxPermSize is. Using Hotspot as our JVM, we will introduce you to the following topics:

Garbage Collector (GC)
Which JVM?
JVM Command Options

Garbage Collector

GC provided by Hotspot VM is a generational GC which is based on two observations:

The most recently created objects are also those most likely to become unreachable quickly
There are few references from older to younger objects

The advantage of a generational GC is that each generation can be managed by the garbage collection algorithm most appropriate for its characteristics. Hotspot VM divides its heap space into three generational spaces:

Young Generation
- When a Java application allocates Java objects, those objects are allocated in the young generation space
- Is typically small and collected frequently
Old Generationn
- Objects that are longer-lived are eventually promoted, or tenured, to the old generation
- Is typically larger than the young generation, and its occupancy grows more slowly
Permanent Generation
- Holds VM and Java class metadata as well as interned Strings and class static variables

Minor vs Full GC

A garbage collection occurs when any one of those three generational spaces is considered full and there is some request for additional space that is not available. There are two types of garbage collection activities: minor and full. When the young generation fills up, it triggers a minor collection in which the surviving objects are moved to the old generation. When the old generation fills up, it triggers a full collection which involves the entire object heap.

Minor GC

Occurs when the young generation space does not have enough room
Tends to be short in duration relative to full garbage collections

Full GC

Occurs when the VM determines there is not enough available space for object promotions from the next minor garbage collection
Takes a longer time depending upon the heap size. However, if it takes longer than 3 to 5 seconds, then it's too long^[1].

Full garbage collections typically have the longest duration and as a result are the number one reason for applications not meeting their latency or throughput requirements. The goal of GC tuning is to reduce the number and frequency of full garbage collections experienced by the application. To achieve it, we can approach from two sides:

From the system side

You should use as large a heap size as possible without causing your system to "swap" pages to disk. Typically, you should use 80 percent of the available RAM (not taken by the operating system or other processes) for your JVM^[1].
The larger the Java heap space, the better the garbage collector and application perform when it comes to throughput and latency

From the application side

A reduction in object allocations, more importantly, object retention helps reduce the live data size, which in turn helps the GC and application to perform.

OutOfMemoryError

The dreaded OutOfMemoryError is something that no Java programmer ever wishes to see. Yet it can happen, particularly if your application involves a large amount of data processing, or is long lived.

The total memory size of an application includes:

Java heap size
Thread stacks
I/O buffers
Memory allocated by native libraries

If an application runs out of memory and JVM GC fails to reclaim more object spaces, an OutOfMemoryError exception will be thrown. The only way to fix it is to adjust heap size. We will discuss how to fix it in the following sections.

Which JVM?

You can use jps (Java Virtual Machine Process Status Tool) to list all local VM identifiers of instrumented HotSpot Java Virtual Machines (JVMs) on the target Linux system. For example, on my system, it lists:

$ jps 
17291 Server
17468 Jps
7883 Launcher

This list includes one Integrated WebLogic Server (i.e., Server) and one JDeveloper (i.e., Launcher). The reason for us to know which JVM throws the OutOfMemoryError is because each application uses its own configuration file to start its JVM and you need to know where to find it.

For example, to change heap space sizes, you can modify those parameters in:

JDeveloper
- $JDEV_HOME/jdev/bin/jdev.conf
WebLogic Server
- <Domain Location>/bin/setDomainEnv.sh
Eclipse
- <Eclipse Installation Location>/eclipse.ini

JVM Command Options

GC tuning is non-trivial. Finding the optimal generation space sizes involves an iterative process^[3]. Here we assume you have successfully identified the optimal heap space sizes for your application. Then you can use the following JVM command options to set them:

GC Command Line Options	Description
-Xms	Sets the initial and minimum size of java heap size
-Xmx	Sets the maximum size of java heap size
-Xmn	Sets the initial, minimum, and maximum size of the young generation space. Note that the size of the old generation space is implicitly set based on the size of the young generation space.
-XX:PermSize=<n>[g\|m\|k]	Sets the initial and minimum size of permanent generation space
-XX:MaxPermSize=<n>[g\|m\|k]	Sets the maximum size of permanent generation space

References

Tuning Java Virtual Machines (JVMs)
Diagnosing Java.lang.OutOfMemoryError
Java Performance by Charlie Hunt and Binu John
Java HotSpot VM Options
GCViewer (a free open source tool)

hashCode() and equals() in Java

2012-01-07T14:44:00.000-08:00

Java object's hash code is important to the performance of hash tables and other data structures that store objects in groups ("buckets") based on their computed hash values. Good implementation of hashCode() must:

Follow its general contract^[1]
Generate values that are evenly distributed for varied inputs to avoid clustering

Overriding equals() and hashCode() in your class needs to be considered together. In this article, we'll examine why.

Object Identity vs. Logical Identity

Object identity

For two object references x and y, two objects are equal if and only if x and y refer to the same object. This is the default behavior of java.lang.Object.equals().

Logical identity

For two value object references x and y, two value objects are equal if their values are identical even they may refer to different objects.

When to Override equals()

Your class needs to override the default object identity behavior if logical identity is its desired behavior and a superclass has not already overridden Object's default equals() implementation.

Override hashCode() If equals() Is Overridden

An object's hashCode() method digests the data stored in the object into a single hash value (a 32-bit signed integer). Hash value cannot be used as a unique identifier for an object because hashCode() is not required to produce distinct integer results for unequal objects based on its contract. However, a good hash function tends to produce unequal hash values for unequal objects.

Always override hashCode() when you override equals(). Failure to do so will prevent your class from functioning properly in conjunction with all hash-based collections, including

HashMap
HashSet
Hashtable

The reason is that one of the general contract of hashCode dictates that:

If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.

If you override equals() by changing its behavior from object identity to logical identity, then your hashCode() must produce the same hash value for two logically identical objects. However, the default hashCode() is typically implemented by converting the internal address of the object into an integer. Therefore, the default hashCode() will return different hash values for two logically identical objects, which violates the general contract.

Queries on hash-based collections should run in linear time. If a bad hash function is used, it might run in quadratic time. For example, if a hashCode() always returns a fixed hash value, hash tables essentially degenerate to linked lists.

As with any general hashing function, collisions are possible. If that happens, objects will be put in groups (or buckets) based on their computed hash values.

Summary

If a class overrides equals(), it must override hashCode()
equals() and hashCode() must use the same set of significant fields of your object
- You can exclude redundant fields which can be computed from other significant fields that are included in the computation
- If you exclude redundant fields, treat them the same way in both methods
If two objects are equal, then their hashCode values must be equal as well
- However, unequal objects need not produce distinct hash values
If the object is immutable, then hashCode is a candidate for caching and lazy initialization

java.lang.Object
Equals and Hash Code in Java
Effective Java by Joshua Bloch

IT Job Interview Questions

2012-01-07T11:12:00.001-08:00

Questions

What's the next number in this sequence: 10, 9, 60, 90, 70, 66 … ?
Using only a four-minute hourglass and a seven-minute hourglass, measure exactly nine minutes—without the process taking longer than nine minutes.
```
    +---+
    | 1 |
+---+---+---+
| 2 | 3 | 4 |
+---+---+---+
| 5 | 6 | 7 |
+---+---+---+
    | 8 |
    +---+
```
Rearrange the above numbers in the squares such that any adjacent numbers (for example, 1 and 2 or 6 and 7) are not next to each other horizontally, vertically, or diagonally. For example, in the above figure, 1 and 2 are next to each other diagonally, which violates the rule.
Three people work together to figure out their average salary without telling anybody his/her own salary.

Answers

Spell the numbers out: (Ten, Nine, Sixty, Ninety, Seventy, Sixty-six). A correct response will have nine letters: 96.
- Lesson learned here: If you tried to solve the series by looking for patterns and failed, look at the question from different angles.
Start both hourglasses at 0 minutes. Flip over the four-minute glass when it runs out (at 4:00); ditto for the seven-minute glass (at 7:00). When the four-minute glass runs out the second time (at 8:00), the seven-minute glass will then have one minute of sand in its lower bulb. Flip the seven-minute glass over again and let the minute of sand run back. When the last grain falls, that will be nine minutes.

Lesson learned here: 4 + 3 + 1 + 1. The important event is when the glass runs out the sand. So, the decision to make involves when to flip the glass and which glass.

```
    +---+
    | 7 |
+---+---+---+
| 3 | 1 | 4 |
+---+---+---+
| 5 | 8 | 6 |
+---+---+---+
    | 2 |
    +---+
```
- Lesson learned here: Place 1 and 8 at the center, which they are the most distant away. Then place 2 and 7 at the opposite sides. Finally, arrange 3-6 to be separate from each other.
Do it this way:
1. Each person chooses a random number and adds that number to his/her salary
2. At the first run, pass that number to next person and add them up.
3. Now, we have the sum of three person's salary plus 3 random numbers.
4. At the second run, remove his/her random number from the total and pass the new total to the next person.
5. Now, we have the sum of 3 person's salary. Just divide it by 3.
Lesson learned here: Adding a random number to the salary helps encrypt his/her salary. Then work together as described in two runs.

References

Answers to Google Interview Questions

Starting the CPU Profiler in JDeveloper

2012-01-03T21:43:00.000-08:00

JDeveloper offers two kinds of profilers: The CPU Profiler and the Memory Profiler, for local as well as remote profiling.

CPU Profiling enables you to identify the most expensive methods and threads in your program.
Memory profiling helps you to find out how your program is using the Java heap.

In this article, we will show you how to:

Set Options for the CPU Profiler
Start the CPU Profiler

CPU Profiler

The CPU Profiler tabulates and displays statistical data on the performance of your application. It enables you to profile your code in one of two modes:

Sample CPU Time
Method Call Count

In Figure 1, it shows the result of method call count operation.

Figure 1. Hotspots view of the method call count operation

Figure 2. Call Stacks view of the method call count operation

The CPU Profiler displays data in two views:

Hotspots
Call Stacks

Also, depending on the mode of operation, they display different information.

In the method call count operation, these views show:

Hotspots
- all the methods and the number of times they were called (see Figure 1)
Call Stacks
- the Java platform methods called, sorted by thread group (see Figure 2)

In the time sampling mode of operation, these views show:

Hotspots
- all Java platform methods and all methods they call, sorted by time usage
- the cumulative amount of CPU time spent in each method
Call Stacks
- the Java platform methods called in their call hierarchy

Setting Options for the CPU Profiler

You can specify if you want the Profiler to sample CPU time usage by your application, or to count method calls. Note that you can choose one mode at a time, not both.

To set CPU Profiler options:

In the navigator, double-click the project you want to profile to open the Project Properties dialog.
Click Run/Debug/Profiler to open the Project Properties - Run/Debug/Profile page.
Click Edit.
In the Edit Run Configuration dialog, set the options as desired on the Tool Settings - Profiler - CPU page. You can specify if you want the profiler to sample CPU time or count method calls. In Figure 3, we want the profiler to count method calls.
When finished, click OK to close the Edit Run Configuration dialog.

Figure 3. Edit Run Configuration Dialog

Starting the CPU Profiler

Starting a CPU profiling session will automatically run your program. Once the CPU profiler window is open (see Figure 1), you can begin a use case to profile your application.

To start the CPU Profiler:

In the navigator, select the project you want to profile. For example, OsmPublicUi.
From the main menu, choose Run > CPU Profile OsmPublicUi.jpr.

The CPU Profiler opens and runs your application.

Click the Begin Use Case icon to begin a profiling

Figure 4. Starting the CPU Profiler

More Hints

If no default run target is specified in the Launch Settings page of the Edit Run Configuration dialog (Application menu > Project Properties > Run/Debug/Profile), the Choose Default Run Target dialog opens. Use this dialog to specify the default run target.

If you want to profile your application immediately when the profiler is launched, select the Begin Use Case on Application Startup checkbox in Profiler page of Edit Run Configuration dialog (see Figure 5).

If you want to analyze a specific method or class you might be interested in, enter the name of a particular method or class in your application in Method Filter (see Figure 5) at the options setting step.

References

Oracle® Fusion Middleware User's Guide for Oracle JDeveloper 11g Release 2 (11.1.2.0.0) Profiling a Project

Volume Rendering using MapReduce

2011-12-04T09:05:00.002-08:00

In [1], it has given a few examples of applications that can be easily expressed as MapReduce computations:

Distributed Grep
Count of URL Access Frequency
Reverse Web-Link Graph
Term-Vector per Host
Inverted Index

There are many other applications that can be easily expressed in MapReduce programming model. In this article, we will show one of them — Volume Rendering.

Applying MapReduce

To determine if MapReduce might be a potential solution to a concurrent programming. Here are the questions to ask:

Does the algorithm break down into two separate phases (i.e., Map and Reduce)?
Can the data be easily decomposed into equal-size partitions in the first phase (i.e., Map)?
Can the same processing be applied to each partition, with no dependencies in the computations, and no communication required between tasks in the first phase?
Is there some “mapping” of data to keys involved?
Can you “reduce” the results of the first phase to compute the final answer(s)?

If all the answers are yes, you have an ideal candidate for the MapReduce computation. In [2], Jeff A. Stuart et al. have demonstrated a multi-GPU parallel volume rendering implementation built using the MapReduce programming model.

Volume Rendering

In [2], Jeff A. Stuart el al. used a volume rendering technique called segmented ray casting [5] (or ray partitioning [6]).

In [3,4], I and my colleagues have demonstrated an alternative way of parallel implementation of volume rendering on Denali. In Fig. 1, we see that sample points along the rays with the same distance from the image plane are in the same plane. So, instead of casting rays, we can equally well sample the volume perpendicular to the viewing direction at different distances from the image plane. This parallelization scheme is called parallel plane cutting.

Figure 1. Parallel plane cutting vs. segmented ray casting

In this article, I'll explore the possibility of adapting parallel plane cutting to MapReduce computation.

MapReduce Basics^[7,8]

MapReduce is an algorithmic framework, like divide-and-conquer or backtracking. Its model derives from the map and reduce combinators from a functional language like Lisp. It is an abstraction that allows Google engineers to perform simple computations while hiding the details of:

Parallelization
Data distribution
Load balancing
Fault tolerance

A MapReduce job is a unit of work that the client wants to be performed: it consists of:

Input data
MapReduce program
Configuration information

The user configures and submits a MapReduce job to the framework (e.g., Hadoop), which will decompose the job into a set of map tasks, shuffles, a sort, and a set of reduce tasks. The framework will then manage the distribution and execution of the tasks, collect the output, and report the status to the user.

A MapReduce job implemented in Hadoop is illustrated below:

Figure 2. Components of a Hadoop's MapReduce Job^[7]

The data flow of the model is shown in Figure 3. This diagram shows why the data flow between map and reduce tasks is colloquially known as “the shuffle,” as each reduce task is fed by many map tasks.

Figure 3. Data Flow of MapReduce programming model

Map and Reduce Tasks

In this article, we will use Hadoop as the framework for our design consideration. Hadoop supports the MapReduce model which was introduced by Google as a method of solving a class of petascale problems with large clusters of inexpensive machines. Hadoop runs the MapReduce job by dividing it into tasks, of which there are two main types:

Map tasks
Reduce tasks

The idea behind map is to take a collection of data items and associate a value with each item in the collection. That is, to match up the elements of the input data with some relevant value to produce a collection of key-value pairs. In terms of concurrency, the operation of pairing up keys and values should be completely independent for each element in the collection.

The reduce operation takes all the pairs resulting from the map operation and does a reduction computation on the collection. The purpose of a reduction is to take in a collection of data items and return a value derived from those items. In more general terms, we can allow the reduce operation to return with zero, one, or any number of results. This will all depend on what the reduction operation is computing and the input data from the map operation.

Data Decomposition

As shown in Figure 2, the first design consideration is data composition (or split). There are at least two factors to be considered:

Data locality
Task granularity vs. parallel overhead cost

Data locality promotes performance. Hadoop does its best to run the map task on a node where the input data resides in (Hadoop Distributed Filesystem) HDFS. However, reduce tasks don’t have the advantage of data locality—the input to a single reduce task is normally the output from all mappers. For our volume rendering example, local sub-volume data will help the performance of map tasks.

Fine-grain parallelism allows for a more uniform distribution of load among nodes, but has the potential for a significant overhead. On the other hand, Coarse-grain parallelism incurs a small overhead, but may not produce a balanced loading. For our volume rendering, there will be an optimal sub-volume size (TBD) that incurs a smaller overhead while produces a better load balancing.

InputFormat

In Hadoop (see Figure 2), user-provided InputFormat can be used for custom data decomposition. An InputFormat describes both how to present the data to the Mapper and where the data originates from. An important job of the InputFormat is to divide the input data sources (e.g., input files) into fragments that make up the inputs to individual map tasks. These fragments are called splits and are encapsulated in instances of the InputSplit interface.

In the parallel cutting plane approach, we subdivide volume into sub-volumes for the rendering. Volume data can be stored in different formats. To simplify this discussion, we assume our input data are stored in sub-volumes (i.e., voxels belonging to the same sub-volume are stored consecutively and in an individual file).

Objects which can be marshaled to or from files and across the network must obey a particular interface, called Writable, which allows Hadoop to read and write the data in a serialized form for transmission. If the Objects are Keys, WritableComparable interface should be used instead.

To support our volume renderer, a custom InputFormat with two custom data types (i.e., SubVolumeKey and SubVolumeValue) needs to be created. A high level description of the implementation is provided below:

public class VolumeInputFormat extends
SequenceFileInputFormat {

public RecordReader getRecordReader(
InputSplit input, JobConf job, Reporter reporter)
throws IOException {

reporter.setStatus(input.toString());
return new VolumeRecordReader(job, (FileSplit)input);
}
...
}

The RecordReader implementation is where the actual file information is read and parsed.

class VolumeRecordReader implements RecordReader {

public VolumeRecordReader (JobConf job, FileSplit split) throws IOException {
..
}

public boolean next(SubVolumeKey key, SubVolumeValue value) throws IOException {
// get next sub-volume
}

public Text createKey() {
return new SubVolumeKey();
}

public Point3D createValue() {
return new SubVolumeValue ();
}
...
}

In SubVolumeKey, you need to provide the following minimum information:

2D footprint offset (Fx, Fy)
Transformation matrix (M)
3D sub-volume offset (Vx, Vy, Vz)
Resampling mode (R)
3D Zooming and 2D Scaling factors (Z and S)
Projection function (P; for example max operation)

Resampling of sub-volumes on each cutting plane can be done independently as long as we can provide sufficient information as shown in the sample SubVolumeKey to each map task. For the detailed description of SubVolumeKey's parameters, refer to [3,4].

Map Function

In this article, we will use Maximum Intensity Projection (MIP) as our volume rendering example. In scientific visualization, MIP is a volume rendering method for 3D data that projects in the visualization plane the voxels with maximum intensity that fall in the way of parallel rays traced from the viewpoint to the plane of projection.

Same principles used for MIP can be applied to Isosurface Rendering (SR). In SR, a Z-buffer or depth matrix is generated as the result. This matrix is actually a 2D image whose values are the depth values at which an isosurface threshold occurs for a given viewing direction. A shading procedure using depth-gradient shading is then applied to generate a colored image.

In [3], we have demonstrated other parallel volume rendering methods too:

Multi-Planar Reformatting
Volume Resampling
Ray Sum

MIP has a nice property—you can apply the reduction computations to individual items and partial results of previous reductions:

max(0, 20, 10, 25, 15) = max(max(0, 20, 10), max(25, 15)) = max(20, 25) = 25

The map task of volume rendering is to generate 2D footprints out of a given sub-volume. To perform projection, we apply the transformation matrix (M) to the volume coordinates (Vx, Vy, Vz) and find the bounding box of each sub-volume. Based on the bounding box and zooming factor (Z), we can find out number of cutting planes need to be sampled in the sub-volume. In x and y directions, all coordinates are rounded or truncated to the closest discrete pixel position in the image plane. In z direction, we define discrete plane levels (not necessary integer coordinates) and all coordinates are rounded or truncated to the closest plane level. After the adjustment of the coordinates of the bounding box as described above, we sample the bounding box of the sub-volume via plane cutting.

For MIP, the map task includes the following sub-tasks:

Resample voxels on each cutting plane
Prepare intermediate results for the consumption of reduce tasks

Each map task will generate as many 2D footprints as required to be sent to reduce tasks. 3D resampling can be done in either point sampling or linear interpolation. The projected footprint will then be scaled based on the 2D scaling factor (S) before being sent out.

Sort and Shuffle

Custom data types are needed for the intermediate results (i.e., 2D image tiles):

SubImageKey
SubImageValue

In SubImageKey, you need to provide the following minimum information:

2D footprint offset (Fx, Fy)
Projection function (P; for example max operation)
2D footprint distance (Fz; but this is not needed in MIP)

The implementation of compareTo method in SubImageKey, which implements a WritableComparable interface, should use (Fx, Fy) in the comparison for the shuffle or sort. For MIP, the ordering of intermediate results doesn't matter.

Reduce Function

The footprint of each sub-volume after projection is a 2D image tile. In Figure 4, we see that image tiles may overlay each other. The final image is created by recombining image tiles. Therefore alignment of image tiles in the projection and recombination process is an important task in this work. If not correct, you may introduce artifacts into the final image. For medical imaging, none of such artifacts can be tolerated.

Figure 4. Projection and Recombination

For MIP, the reduce task includes the following sub-tasks:

Apply projection function (i.e., max) to each pixels on the intermediate results
Assemble the final image in a global output file with a specified format.

Conclusion

For a divide-and-conquer approach, the construction of the final image requires a number of stages. Image tiles of individual sub-volumes are generated after sampling and blending. A recombination process which takes care of pixel alignments is used to place these tiles into the final image under a specific merging condition. Finally, a post-rendering process called Z merging, with a depth compare done upon merging, can be used to integrate volume images with 3D graphics.

Finally, I want to use this article to pay tribute to Dr. Bruce H. McCormick (1928 - 2007) who is my most respected college professor and Ph.D. adviser.

References

Introduction to Parallel Programming and MapReduce
Mult-GPU Volumne Rendering using MapReduce
S. Y. Guan and R. Lipes, “Innovative Volume Kendering Using 3D Texture Mapping,” Proceedings of Medical imaging 1996-Image Capture. Formatting, and Display, vol. 2 164. pp. 382-392, Feb. 1994.
S. Y. Guan, Bleiweiss, A., Lipes, R. “Parallel Implementation of Volume Rendering on Denali Graphics Systems,” Parallel Processing Symposium, 1995. Proceedings., 9th International, pp. 700-706,1995.
E. Camahort and I. Chakravmty, “Integrating Volume Data Analysis and Rendering on Distributed Memory Architectures,” Proceedings of 1993 Parallel Rendering Symposium, pp. 89-96, San Jose. CA, Oct. 1993.
W. M. Hsu, “Segmented Ray Casting for Data Parallel Volume Rendering,” Proceedings of 1993 Parallel Rendering Symposium. pp. 7-14, San Jose, CA, Oct. 1993.
Pro Hadoop by Json Venner
Hadoop: The Definitive Guide, Second Edition by Tom White
Yahoo! Hadoop Tutorial

Sub-flow Design Pattern

2011-11-05T13:25:00.000-07:00

A design pattern is a formal documentation of a proven solution to a common problem. Within Oracle Fusion Web Applications^[1], there are many design patterns embedded in their design. One of them is sub-flow design pattern.

Before you start, read this companion article first.

Usage

In sub-flow design pattern, there are two task flows involved:

Parent task flow (top-level)
Sub-flow

In Oracle Fusion Web Applications, all top-level task flows can be bookmarked and be launched from either task list or Recent Items menu. However, if the application requires that sub-flows can also be bookmarked and be launched from Recent Items menu. Then this sub-flow design pattern can be utilized for that functionality.

If sub-flows are bookmarked, it can be relaunched from Recent Items menu. In the sub-flows, it's required that users can also navigate back to its parent flow. Sub-flow design pattern also takes that into consideration.

Overview

To record sub-flows into the Recent Items list, applications need to call openSubTask API right before sub-flows are launched^[2]. openSubTask takes parameters similar to openMainTask's. One of them is task flow ID. For this, you need to specify parent flow's ID (or main task's ID). In other words, sub-flows need to be executed via parent flow even they are launched from Recent Items menu. See Sample Implementation section for details.

If your sub-flow doesn't need to be bookmarked by Recent Items, you don't need to change anything. Otherwise, you need to modify your parent flow and sub-flow as described in the following task. After the changes, sub-flows can be launched in two ways:

From original flows
From Recent Items menu items using recorded information

Both will start the execution in parent flow. Because sub-flow needs to be launched via parent flow in the 2nd case above, you need to change parent flow in this way:

Add a new router activity at the beginning of the parent flow. Based on a test condition (to be described later), it will route the control to either the original parent flow or the task flow call activity (i.e., the sub-flow).
Add an optional method call activity to initialize sub-flow before it's launched for the 2nd case (i.e., launching from Recent Items menu). Fusion developers can code the method in such a way that it can navigate to the sub-flow after initializing the parent state. This allows applications to render contextual area, navigating back to parent flow from sub-flow and any other customizations.
Bind openSubTask to the command component (i.e., link or button) which causes the flow navigate to the task flow call activity in the original parent flow. openSubTask API registers the parent flow details (to be launched as a sub-flow later) to the Applications Core task flow history stack.

Usually, you don't need to modify your sub-flow for this task. However, you can consolidate the initialization steps from two execution paths in such a way:

Remove initialization parts from both paths in the parent flow. Instead set input parameters (which to be used as test conditions in sub-flows) in both paths only.
Modify sub-flow to take input parameters.
Add a new method call (say initSubFlow) at beginning of the sub-flow to initialize states in parent flow (for example, parent table) so that sub-flow can be launched in the appropriate context.

Note that the design pattern also requires the application capable of navigating back to parent flow from sub-flow. So, the initialization code should take this into consideration (i.e., set up states to allow sub-flow to navigate back) too.

In the following, we'll use an Employee sample implementation to demonstrate the details of this design pattern.

Sample Implementation

In this Fusion Web Application, users select Subflow Design Pattern from the Task list. They then specify some criteria for searching a specific employee or employees. From the list, they can choose the employee that they want to show the details for. This procedure is demonstrated in the following screen shots:

Ename in the search result table is a link which can be used to navigate to the employee detail page of a specific employee. When this link is clicked, a sub-flow (or nested bounded task flow) is called and it displays the Employee Complete Detail page.

If users would like to add this Employee Complete Detail page of a specific employee (say, employee named 'Allen') to their Recent Items list, application developers need to set up something extra to make this happen. If this page (actually what gets recorded is a bounded task flow whose default page is displayed) has been bookmarked, next time users can click it on the Recent Items menu and launch it directly by skipping the search step (i.e., identify the Employee whose details need to be displayed).

Implementation Details

Our parent task flow named ToParentSFFlow is shown below:

decideFlow in the diagram is the router activity that decides whether the control flow should go to either original parent flow path (i.e., "initParent") or sub-flow path (i.e., "toChild"). The condition we used is defined as follows:

<router id="decideFlow">
 <case>
   <expression>#{pageFlowScope.Empno == null}</expression>
   <outcome id="__9">initParent</outcome>
 </case>

 <case>
   <expression>#{pageFlowScope.Empno != null}</expression>
   <outcome id="__10">toChild</outcome>
 </case>

 <default-outcome>initParent</default-outcome>
</router>

In the test, we check whether Empno variable in the parent flow's pageFlowScope is null or not. #{pageFlowScope.Empno} is set via its input parameter Empno when parent flow is called . The input parameters on the parent flow (i.e., ToParentSFFlow) is defined as follows:

<input-parameter-definition>
  <name>Empno</name>
  <value>#{pageFlowScope.Empno}</value>
  <class>java.lang.String</class>
</input-parameter-definition>

When parent flow is launched from Task List, parameter Empno is not set (i.e., not defined in the Application menu's itemNode). Therefore, it's null and router will route it to "initParent" path.

When sub-flow is recorded via openSubTask API, we set Empno on the parametersList as follows:

<methodAction id="openSubTask" RequiresUpdateModel="true"
                 Action="invokeMethod" MethodName="openSubTask"
                 IsViewObjectMethod="false" DataControl="FndUIShellController"
                 InstanceName="FndUIShellController.dataProvider"
                 ReturnName="FndUIShellController.methodResults.openSubTask_FndUIShellController_dataProvider_openSubTask_result">
     <NamedData NDName="taskFlowId" NDType="java.lang.String"
         NDValue="/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToParentSFContainerFlow.xml#ToParentSFContainerFlow"/>
     <NamedData NDName="parametersList" NDType="java.lang.String"
                NDValue="Empno=#{row.Empno}"/>
     <NamedData NDName="label" NDType="java.lang.String"
                NDValue="#{row.Ename} complete details"/>
     <NamedData NDName="keyList" NDType="java.lang.String"/>
     <NamedData NDName="taskParametersList" NDType="java.lang.String"/>
     <NamedData NDName="viewId" NDType="java.lang.String"
                NDValue="/DemoWorkArea"/>
     <NamedData NDName="webApp" NDType="java.lang.String"
                NDValue="DemoAppSource"/>
     <NamedData NDName="methodParameters"
         NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
</methodAction>

We also set up:

taskFlowId to be parent flow's, not subflow's
label to be subflow's

When end users click on the link (i.e., Ename), which the openSubTask method is bound to, openSubTask will be called. This link component is defined as follows:

<af:column sortProperty="Ename" sortable="false"
           headerText="#{bindings.ComplexSFEmpVO.hints.Ename.label}"
           id="resId1c2">
  <af:commandLink id="ot3" text="#{row.Ename}"
                  actionListener="#{bindings.openSubTask.execute}"
                  disabled="#{!bindings.openSubTask.enabled}"
                  action="toChild">
    <af:setActionListener from="#{row.Empno}"
                          to="#{pageFlowScope.Empno}"/>
  </af:commandLink>
</af:column>

Note that when the link is clicked, actionListener and action specified on the link are executed and in that order. Also note that openSubTask needs to be called only from the original parent flow path (i..e, "initParent"), not sub-flow path(i.e., "toChild).

EmployeeeDetails activity in the above figure is a Task Flow Call activity which invokes our sub-flow (i.e., ToChildSFFlow). Before sub-flow is executed, you need to add some initialization steps. These initialization steps could include, but not limited to:

Set up parent states. For our example, we need to set selected employee's row to be current.
Set up contextual area state.
Set up states to allow sub-flow to navigate back to parent flow.

There are two approaches to set up initialization steps:

In the parent flow
In the sub-flow

For the first approach, you can add logic to initialize both paths before the task flow call activity in the parent flow. For the second approach, you initialize states in the sub-flow by using input parameters of the sub-flow. For example, in our example, sub-flow will take an input parameter named Empno. So, the second approach just postpone the initialization to the sub-flow.

Let's see how input parameters are defined in Task Flow Call activity and sub-flow.

Here is the definition of input parameters in our Task Flow Call activity:


<task-flow-call id="EmployeeDetails">
     <task-flow-reference>
       <document>/WEB-INF/oracle/apps/xteam/demo/ui/flow/ToChildSFFlow.xml</document>
       <id>ToChildSFFlow</id>
     </task-flow-reference>
     <input-parameter>
       <name>Empno</name>
       <value>#{pageFlowScope.Empno}</value>
     </input-parameter>
</task-flow-call>

Note that this means that the calling task flow needs to store the value of Empno in #{pageFlowScope.Empno}. For example, from the original parent flow path, it is set to be #{row.Empno} using setActionListener tag. For the sub-flow path, it is set using parent flow's input parameter named Empno. On the sub-flow, we need to specify its input parameters as below:

<task-flow-definition id="ToChildSFFlow">
   <default-activity>TochildSFPF</default-activity>
   <input-parameter-definition>
     <name>Empno</name>
     <value>#{pageFlowScope.Empno}</value>
     <class>java.lang.String</class>
   </input-parameter-definition>
   ...
</task-flow-definition>

Note that the name of the input parameter (i.e., "Empno") needs to be the same as the parameter name defined on the task flow call activity. When parameter is available, ADF will place it in:

#{pageFlowScope.Empno}

to be used within sub-flow. However, this pageFlowScope is different from the one defined in the Task Flow Call activity because they have different owning task flow (i.e., parent task flow vs. sub-flow).

Here is the definition of sub-flow:

In the sample implementation, we chose to implement the initialization step in the sub-flow. Empno is passed as an parameter to sub-flow and used to initialize parent state. When sub-flow is launched, default view activity (i.e., ToChildPF) displays. Before it renders, initPage method on the ChildBean will be executed first. The page definition of the default page is defined as follows:

<pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel">
 <parameters/>
 <executables>
   ...
   <invokeAction id="initPageId" Binds="initPage" Refresh="always"/>
 </executables>
 <bindings>
   ...
   <methodAction id="initPage" InstanceName="ChildSFBean.dataProvider"
                 DataControl="ChildSFBean" RequiresUpdateModel="true"
                 Action="invokeMethod" MethodName="initPage"
                 IsViewObjectMethod="false"
                 ReturnName="ChildSFBean.methodResults.initPage_ChildSFBean_dataProvider_initPage_result"/>
    ...
 </bindings>
</pageDefinition>

As shown above, initPage is specified in the executables tag and will be invoked when the page is refreshed. initPage method itself is defined as follows:

public void initPage()
{
   FacesContext facesContext = FacesContext.getCurrentInstance();
   ExpressionFactory exp = facesContext.getApplication().getExpressionFactory();
   DCBindingContainer bindingContainer =
     (DCBindingContainer)exp.createValueExpression(
         facesContext.getELContext(),"#{bindings}",DCBindingContainer.class).getValue(facesContext.getELContext());
   ApplicationModule am = bindingContainer.getDataControl().getApplicationModule();

   ViewObject vo = am.findViewObject("ComplexSFEmpVO");
   vo.executeQuery();

   Map map = AdfFacesContext.getCurrentInstance().getPageFlowScope();
   if(map !=null){
        Object empObj = map.get("Empno");
        if(empObj instanceof Integer){
            Integer empno =(Integer)map.get("Empno");// new Integer(empnoStr);
            Object[] obj = {empno};
            Key key = new Key(obj);
            Row row = vo.getRow(key);
            vo.setCurrentRow(row);
        }
        else
        {
            String empnoStr = (String)map.get("Empno");
            Integer empno = new Integer(empnoStr);
            Object[] obj = {empno};
            Key key = new Key(obj);
            Row row = vo.getRow(key);
            vo.setCurrentRow(row);
        }
    }
}

In initPage, it takes input parameter Empno (i.e., from #{pageFlowScope.Empno}) as a key to select a row and set it to be the current row in the master table (i.e., Employee table).

References

Book Review: "Oracle WebCenter 11g PS3 Administration Cookbook"

2011-09-22T08:54:00.001-07:00

There are three major components in the WebCenter product stack:

WebCenter Framework
- Allows you to embed portlets, ADF Taskflows, content, and customizable components to create your WebCenter Portal application
- All Framework pieces are integrated into the Oracle JDeveloper IDE, providing access to these resources as you build your applications
WebCenter Services
- Are a set of independently deployable collaboration services
- Incorporates Web 2.0 components such as content, collaboration, discussion, announcement and communication services
WebCenter Spaces
- Is an out-of-the-box WebCenter Portal application for team collaboration and enterprise social networking
- Is built using the WebCenter Framework, WebCenter services, and Oracle Composer

As the strategic portal product of Oracle, WebCenter Framework plays in the Enterprise portal space, and WebCenter Services/Spaces plays in the Collaboration Workspace space.

What's Portal Application?

A portal can be thought of as an aggregator of content and applications or a single point of entry to a user's set of tools and applications. It is a web-based application that is customizable by the end-user both in the look and feel of the portal and in the available content and applications which the portal contains.

The key elements of portals include:

Page hierarchy
Navigation
Delegated administration and other security features
Runtime customization and personalization.

To design a successful enterprise web portal is hard, but getting easier and more practical with Oracle WebCenter which is built on top of Oracle ADF technology. As an enterprise portal, security is extremely important. Unauthorized people should never get access, and different groups may have different permissions. Customers, partners and employees should be able to use a single login to access all relevant information and applications.

The Book

To design, test, deploy, and maintain a successful web portal is nontrivial to say the least. Therefore, a cookbook like Oracle WebCenter 11g PS3 Administration Cookbook is needed. In fourteen chapters, it provides over a hundred step-by-step recipes that help the reader through a wide variety of tasks ranging from portal and portlet creation to securing, supporting, managing, and administering Oracle WebCenter.

In the book, it covers many new features introduced by the 11g R1 Patch Set 3 version of the Oracle WebCenter product. It also touches upon all three components: WebCenter Framework, WebCenter Services, and WebCenter Spaces and roughly in that order. Besides important topics such as customization and security , it also discuss the analytics aspect of the product (i.e., Activity Graph).

Resource Catalog

Using resource catalog as an example, in this book, you'll learn that:

How to create a resource catalog either at design time or runtime
How to specify a catalog filter or a catalog selector
How to add a link to the resource catalog
How to add an existing resource catalog to the catalog
How to add custom components to a resource catalog
How to add custom folder to the resource catalog

At each step, you'll learn how it works and why. For example, when you add a resource catalog at runtime, an XML file will also be created, but it will be stored in the MDS (Metadata Service Repository) which is a repository used by WebCenter to store metadata.

Trade-offs

After the introduction of different approaches, the author also discusses the trade-offs of each approach. For example, with WebCenter Spaces, it allows you to build collaborative intranets without needing to develop a lot. The problem you will be having with WebCenter Spaces is that it is not as easily customizable as a regular WebCenter Portal application. Therefore, you can combine the best of both worlds. When you need a high level of customization or you need to extend the site with your custom functionality, then you should create a WebCenter Portal application. When you need a collaborative environment where customization or added functionality is not as important as the collaborative services, then go for WebCenter Spaces.

References

ADF View Criteria By Example

2011-09-17T13:24:00.000-07:00

There are different filtering approaches to query row data provided in Oracle ADF 11g:

By adding WHERE clause to View Object SQL statement
By creating View Criteria Programmatically
By using named View Criteria

In this article, we will examine these different approaches followed by the discussion of view criteria.

Not that all three examples shown in the article are defined in the application module.

Adding WHERE Clause

In the first example (i.e., getChannel1), it gets the query statement from the View Object and appends it with a WHERE clause. Then the PreparedStatement is executed with specified filtering.

public OracleCachedRowSet getChannel1(Long channelId)
throws SQLException
{
ResultSet rs = null;
try
{
ViewObjectImpl vo =
(ViewObjectImpl) this.findViewObject("ChannelOnly");
StringBuffer query = new StringBuffer(vo.getQuery());
query.append(" where ChannelEO.CHANNEL_ID =").append(channelId);
DBTransaction txn = this.getDBTransaction();
PreparedStatement ps =
txn.createPreparedStatement(query.toString(), 1);
rs = ps.executeQuery();
OracleCachedRowSet ocs = new OracleCachedRowSet();
ocs.populate(rs);

return ocs;
}
catch (Exception e)
{
if (AppsLogger.isEnabled(AppsLogger.SEVERE))
{
AppsLogger.write(OsmmSetupUiModelAMImpl.class, e);
}
}
finally
{
if (rs != null)
rs.close();
}
return null;
}

Creating View Criteria Programmatically

In the second example (i.e., getChannel2), it shows that a ViewCriteria object is created at runtime by using ViewCriteriaRow's, which in turn are composed of ViewCritiaItem's. Then this ViewCriteria object is applied to the View Object and used in the filtering.

 public  void getChannel2(Long channelId)
{
// Create and populate criteria rows to support query-by-example.
ViewObject channelVO = this.findViewObject("ChannelOnly");
ViewCriteria vc = channelVO.createViewCriteria();
ViewCriteriaRow vcRow = vc.createViewCriteriaRow();

// ViewCriteriaRow attribute name is case-sensitive.
// ViewCriteriaRow attribute value requires operator and value.
// Note also single-quotes around string value.
ViewCriteriaItem jobItem = vcRow.ensureCriteriaItem("ChannelId");
jobItem.setOperator("=");
jobItem.getValues().get(0).setValue(channelId);
vc.add(vcRow);

channelVO.applyViewCriteria(vc);

// Multiple rows are OR-ed in WHERE clause.
System.out.println("Demo View Criteria");

// Should print channel with specified channel ID
printViewObject(channelVO);
}

public  void printViewObject(ViewObject vo)
{
// Execute the query, print results to the screen.
vo.executeQuery();

// Print the View Object's query
System.out.println("Query: " + vo.getQuery());

while (vo.hasNext())
{
Row row = vo.next();
String rowDataStr = "";

// How many attributes (columns) is the View Object using?
int numAttrs = vo.getAttributeCount();

// Column numbers start with 0, not 1.
for (int columnNo = 0; columnNo < numAttrs; columnNo++)
{    
// See also Row.getAttribute(String name).    
Object attrData = row.getAttribute(columnNo);
rowDataStr += (attrData + "\t");
}
System.out.println(rowDataStr);
}
}

Using Named View Criteria

In the third example (i.e., getChannel3), it finds a named View Criteria (i.e., findByChannelId) which is defined at design time. After setting the value of named Bind Variable (i.e., ChannelIdBV), the view criteria is applied to the View Object and used in querying the row data.

public Row[] getChannel3(Long channelId)
{
ChannelVOImpl viewObj = (ChannelVOImpl) this.getChannelOnly();
if (viewObj != null)
{
ViewCriteria vc = viewObj.getViewCriteria("findByChannelId");
viewObj.setNamedWhereClauseParam("ChannelIdBV", channelId);
viewObj.applyViewCriteria(vc);
viewObj.executeQuery();
viewObj.setRangeSize(-1);
Row[] allRows = viewObj.getAllRowsInRange();
return allRows;
}
return null;
}

What's View Criteria

Before the advent of Oracle ADF 11g, to show an employee list filtered by company role on one page and by department number on another page, you would have needed to either create separate view objects for each page or write custom code to selectively modify a view object's WHERE clause and bind variable values. With the new release, you can now use a single view object with multiple named view criteria filters to accomplish the same task.

A view criteria you define lets you specify filter information for the rows of a view object collection. The view criteria object is a row set of one or more view criteria rows, whose attributes mirror those in the view object. The view criteria definition comprises query conditions that augment the WHERE clause of the target view object. Query conditions that you specify apply to the individual attributes of the target view object. Check out here for:

How to Create Named View Criteria Declaratively
How to Test View Criteria Using the Business Component Browser
How to Create View Criteria Programmatically

Advantages of Using Named View Criteria

Among the different approaches, the third one is the preferred approach. This is because view criteria that you define at design time can participate in these scenarios where filtering results is desired at runtime:

Supporting Query-by-Example search forms that allow the end user to supply values for attributes of the target view object^[2].
Filtering the list of values (LOV) components that allow the end user may select from one attribute list (displayed in the UI as an LOV component)^[3].
Validating attribute values using a view accessor with a view criteria applied to filter the view accessor results^[4].
Creating the application module's data model from a single view object definition with a unique view criteria applied for each view instance^[5].

References

Book Review: "Overview of Oracle Enterprise Manager Grid Control 11g R1: Business Service Management"

2011-08-14T19:05:00.000-07:00

There are different console applications or flavors provided in Oracle Enterprise Manager (OEM):

OEM Database Control
OEM Application Server and Fusion Middleware Control
OEM Grid Control

The Business Service Management (BSM) capabilities of Oracle Enterprise Manager are available only in the Grid Control flavor.

In this book "Overview of Oracle Enterprise Manager Grid Control 11g R1: Business Service Management", it covers OEM's Business Service Management capabilities in great details as described in this article.

Business Service Management

Business Service Management (BSM) is a methodology for monitoring and measuring Information Technology (IT) services from a business perspective. It allows IT departments to operate by service rather than by individual manageable entity or target.

BSM software and services are provided by major vendors. Oracle Enterprise Manager (OEM) 11g is a product offering from Oracle that provides solutions to the typical IT infrastructure management issues.

Management Issues

Any enterprise IT infrastructure contains numerous disparate components that are geographically distributed across various data centers. These components include:

Hardware components
- Such as servers hosting different applications, network switches, routers, storage devices, and so on
Software components
- Such as operating systems, database servers, application servers, middleware components, packaged applications, distributed applications, and so on

To make things even worse, an IT infrastructure also have the following characteristics:

Hardware and software could be sourced from multiple vendors
Multiple versions of the same software product, from the same vendor, could be deployed across the enterprise
Newer technologies such as service-oriented architectures (SOA), virtualization, cloud computing, portal frameworks, grid architectures, and mashups within an organizations make troubleshooting and monitoring of business services very difficult

These heterogeneous, disparate and geographically distributed components give rise to the complexity of IT management issues.

The Needs

Facing these challenges, a successful management solution must:

Have the capability to model, monitor, administer, and configure higher-level logical entities that map to business functions
Provide different perspectives to get a comprehensive view of the health of the various business services and the underlying IT infrastructure
Be able to perform complex computations and scale very easily with a simple architecture and a small footprint
Take into consideration the geographical spread of the infrastructure landscape

The Solution

Oracle Enterprise Manager (OEM) is one of the industry leaders in the system management products arena. It provides the following capabilities:

A single unified platform for modeling and managing enterprise data centers
Comprehensive monitoring and management capabilities for the entire Oracle Grid within the enterprise
Discovery, monitoring, and management of various pieces of the IT infrastructure
- Includes Non-Oracle Software Products
Supports both passive and active monitoring paradigms
Two distinct perspectives:
- Target-based focus
  - This provides a highly specialized set of views exclusive for a specific target
- Business service-based focus
  - This provides a holistic view that dwells on different targets within an enterprise and their interactions with each other to achieve a business objective
Capabilities of defining and tracking Service-Level Agreements (SLAs) of different business functions

The Grid Control architecture (see the Figure above) is distributed in nature and relies on the agents to collect data on the individual hosts. It includes the following components:

Oracle Management Agent
- A piece of software installed on a host that collects information about the targets on the host or remote hosts. The collected data is then passed onto the management service.
- In case of remote monitoring (vs. local monitoring), there is no automatic discovery support and the administrator must use the console UI pages to initiate the remote discovery.
Oracle Management Service (OMS)
- This is the brain of the OEM. It acts as the centralized management solution and also acts as the server to which all the management agents upload the collected data.
- The OMS provides current and future insights into business functions and services by looking at the historical data that is stored in its management repository.
OEM Console
- This is the user interface that exposes all the management functionalities to the end user of OEM.
- It provides views into each of the targets and also allows the user to initiate actions and configuration changes on these targets.
Oracle Management Repository
- This is the central repository that is used by the OMS to store all data.

By distributing the data collection to individual agents the Oracle Management Service (OMS) is freed up to perform more important tasks.

The Book

In the book, it has used a travel portal as example to:

Illustrate the concepts of IT infrastructure management
Showcase OEM's BSM capabilities
Provide step-by-step instructions of using OEM

The travel portal provides various business services such as flight search, car rental services, and so on to the end users. It also consumes the payment gateway services from various business partners.

In the travel portal illustration, these services are configured as different service targets such as:

CarRentalService:
- Modeled as a Generic Service target based on the TravelPortal-CarRental-System
FlightSearchWebSite:
- Modeled as a Web Application service based on a Service Test from two different beacons
PaymentGatewayService:
- Modeled as a Forms Application based on the PaymentGatewaySystem
TravelPortalSearchServices:
- Modeled as an Aggregate Service comprising the CarRentalService and FlightSearchWebSite service targets

Resources

Beautifying Table and Column Comments for Design Review

2011-07-26T13:19:00.000-07:00

Data model design is an iterative process. As soon as the conceptual data model is accepted by the functional team, development of logical data model gets started. Once logical data model is completed, it is then forwarded to functional teams for review. A good data model is created by clearly thinking about the current and future business requirements.

To facilitate the review process, you need to present descriptions of entities and attributes in the data model to the functional team. Some database developers prefer working at source level (i.e., SQL DDL). For example, you can present the following EMP table to the team for review:

-- Employee Data
CREATE TABLE "SCOTT"."EMP"
(
"EMPNO" NUMBER(4,0),        -- employee number
"ENAME" VARCHAR2(10 BYTE),  -- employee name
"JOB"   VARCHAR2(9 BYTE),   -- job description
"MGR"   NUMBER(4,0),        -- manager ID
"HIREDATE" DATE,            -- hiring date
"SAL"    NUMBER(7,2),       -- salary
"COMM"   NUMBER(7,2),       -- commission
"DEPTNO" NUMBER(2,0),       -- department number
CONSTRAINT "PK_EMP" PRIMARY KEY ("EMPNO") USING INDEX PCTFREE 10 INITRANS 2 MAXTRANS 255 COMPUTE STATISTICS STORAGE(INITIAL 65536 NEXT 1048576 MINEXTENTS 1 MAXEXTENTS 2147483645 PCTINCREASE 0 FREELISTS 1 FREELIST GROUPS 1 BUFFER_POOL DEFAULT FLASH_CACHE DEFAULT CELL_FLASH_CACHE DEFAULT) TABLESPACE "USERS" ENABLE,
CONSTRAINT "FK_DEPTNO" FOREIGN KEY ("DEPTNO") REFERENCES "SCOTT"."DEPT" ("DEPTNO") ENABLE
)

In this article, we will show another way which presents the following table generated semi-automatically from the offline database using JDeveloper and Microsoft Excel:

Using the first approach, the drawbacks include:

SQL DDL scripts tend to be error-prone
Comments are only for human reader and not part of the DB definitions

That's why we propose the second approach which can resolve these two issues.

Offline Database

In JDeveloper, database development is available offline in the context of a project, allowing developers to create and manipulate schemas of database objects which can be generated to a database or to SQL scripts. Database objects can also be imported from a database into a project. See my previous post for more details.

You can follow the instructions in [1, 2] to create offline database objects. For the demo, I've created a database diagram and drag an existing EMP table from the SCOTT schema to create a table on it.

Adding Comments

Double-click the EMP table component on the diagram to open the Edit Table dialog,

Select Comment in the navigation panel to enter table's comment as shown above.
Select Columns in the navigation panel and navigate them one by one. In the Comment field, enter column's comment as shown above. Click Save All to save your work.

In the Application Navigator, under Offline Database Sources | EMP_DATABASE | SCOTT, right-click the EMP node, and choose Generate To > SQL script ... to create SQL script file named emp.sql.
Open emp.sql in the editor window. Look for comments of table's and columns' at the bottom of the script as shown below:

COMMENT ON TABLE EMP IS 'Employee Data';

COMMENT ON COLUMN EMP.EMPNO IS 'employee number';

COMMENT ON COLUMN EMP.ENAME IS 'employee name';

COMMENT ON COLUMN EMP.JOB IS 'job description';

COMMENT ON COLUMN EMP.MGR IS 'manager ID';

COMMENT ON COLUMN EMP.HIREDATE IS 'hiring date';

COMMENT ON COLUMN EMP.SAL IS 'salary';

COMMENT ON COLUMN EMP.COMM IS 'commission';

COMMENT ON COLUMN EMP.DEPTNO IS 'department number';

Select the above comments and copy them into a text file (i.e., emp.txt).

Generating Comment Table

Start up Microsoft Excel and import text file as follows:
On the Text Import Wizard, you specify delimiters using space and paired single quotes as shown below:

After clicking on Finish button, you can remove column A,B, and E. It will then present you with the final comment table as shown at the beginning of this article.

Conclusion

Comment tables generated in the second approach have the following advantages:

The source of comment table is offline database object which can be validated by JDeveloper and can be source controlled.

They are part of the DB definitions and can be queried as follows:

select comments
from user_tab_comments
where table_name = 'EMP'
/

select column_name, comments
from user_col_comments
where table_name = 'EMP'
order by column_name
/

References

Modeling Data with Offline Database in JDeveloper

2011-07-26T10:38:00.000-07:00

For Oracle Applications developers, the JDeveloper offline database modeler replaces the Oracle Designer repository, or CASE as it was referred to. Applications developers should not use SQL DDL scripts for deployment and source control of database objects, because they tend to error-prone and do not serve as a single source of truth. Instead, developers should use the JDeveloper offline database object files.

What is the Offline Database

JDeveloper provides the tools you need to create and edit database objects, such as tables and constraints, outside the context of a database, using the offline Database model. You can create new tables and views, and generate the information to a database, or you can import database objects from a database schema, make the changes you want, and generate the changes back to the same database schema, to a new database schema, or to a file that you can run against a database at a later date.

Offline Database Model

The JDeveloper Offline database supports the following object types:

Function
Materialized View
Materialized View Log
Package
Procedure
Sequence
Synonym
Table
Trigger
Type
View

Currently, JDeveloper offline DB objects do not support these objects:

Queue
Queue tables
Policy
Context

However, SXML persistence files for these object types can be imported using the applxdf extension.

JDeveloper provides tools to create and edit database objects such as tables, view etc. outside the context of a database. This tool called Offline Database Definition will be used to model physical database objects in Fusion applications. The migration tool will support migrating all user selected database objects defined in CASE to this offline database definition in JDeveloper along with SXML/XDF¹ deployment files.

Metadata SXML Comparison Tool^[3]

Offline table definitions can be version controlled and shared using a source control system. If you just create objects in the DB schema via the database navigator, you have nothing to source control. JDeveloper provides a comparison tool optimized for working with offline table definitions, which handles:

The table data, properties, columns and constraints.
The identity of objects, to track name changes.
Checking for consistency, for example, ensuring:
- That a column which is used in a key is not dropped.
- That a constraint which uses an absent column is not added.
- That a primary key column cannot be options.

Using this comparison tool, you can compare object metadata of the same type from different databases. This comparison depends on SXML. SXML is an XML representation which more closely maps to the SQL creation DDL. Two SXML documents of the same type can be compared and a new SXML document is provided which describes their differences.

Using this comparison tool, you're able to:

Compare object definitions in different JDeveloper projects
- Since the objects to be compared are in separate projects, you need to create a dependency between them to be able to perform this comparison.
Compare versioned copies of DB objects
- Versioning components allows you to browse through the historical changes of a component and make comparison between these versions. With JDEV, it's possible to compare different versions of database models.

Working on Data Modeling at Different Levels:

UML class diagram
- You can create a logical model using a UML class diagram to visually create or inspect classes, interfaces, attributes, operations, associations, inheritance relationships, and implementation relations and transform it to an Offline or Online Database definitions later.
- See this tutorial for how-to.
- You usually do logical modeling using a UML class model in the following steps:
  1. Preparing a class model diagram Environment
  2. Creating a Class Model Diagram
  3. Enhancing the Class Model
  4. Transform the Class Model into a Database Model
Database diagram
- You can follow [4, 5] to create new database diagram.
- You can also drag tables, views, materialized views, synonyms, and sequences from a database schema onto a database diagram, where they become accessible as offline database objects.
Offline Database
- You can create new offline database objects, or capture them from a connection to a live database. After you have finished working with them, you can generate new and updated database definitions to online database schemas or to SQL scripts.
- You can follow the instructions in [4, 5] to create new offline database objects. When you create an offline database, you choose the database emulation (for example, Oracle11g Database Release 1) the offline database should have.
- You can also copy offline database objects to a project. In general, it is a good idea to make sure that the offline database uses the same database emulation as the source database.
- Note that generation to a database is not certified against non-Oracle databases.

Notes

Prior to SXML migration, these were referred to as xdf (extension) files.

References

Language Identification

2011-07-13T11:12:00.000-07:00

Language identification is one of the supervised learning method. In this article, we will cover a specific Processing Resource (PR) in GATE (i.e., TextCat or Language Identification PR). Based on its documentation, it says that it:

Recognizes the document language using TextCat. Possible languages: german, english, french, spanish, italian, swedish, polish, dutch, norwegian, finnish, albanian, slovakian, slovenian, danish, hungarian.

N-Gram-Based Text Categorization

TextCat PR uses N-Gram for text categorization. You can find the details from this article. See the following diagram for its data flow.

There are two phases in the language identification task:

Training
Application

We'll discuss those in the following sections.

Training Phase

In the training phase, the goal is to generate category profiles from the given category samples. In Language Identification PR (or TextCat PR), the categories are languages. So, we take document samples from different languages (i.e., English, German, etc.) and use them to generate category profiles.

These category profiles are already provided in TextCat PR. At runtime, TextCat PR looks for a configuration file named textcat.conf. This files has the following content:

language_fp/german.lm    german
language_fp/english.lm    english
language_fp/french.lm    french
language_fp/spanish.lm    spanish
language_fp/italian.lm    italian
language_fp/swedish.lm    swedish
language_fp/polish.lm    polish
language_fp/dutch.lm    dutch
language_fp/norwegian.lm    norwegian
language_fp/finnish.lm    finnish
language_fp/albanian.lm    albanian
language_fp/slovak-ascii.lm    slovakian
language_fp/slovenian-ascii.lm    slovenian
language_fp/danish.lm    danish
language_fp/hungarian.lm    hungarian

In a sub-folder named language_fp which is relative to the location of textcat.conf, there are multiple category profile files with lm suffix. For example, german.lm is the category profile for German and english.lm is the category profile for English.

Using English profile as an example, its content looks like this:

_     20326
e     6617
t     4843
o     3834
n     3653
i     3602
a     3433
s     2945
r     2921
h     2507
e_     2000
d     1816
_t     1785
c     1639
l     1635
th     1535
he     1351
_th     1333
...

On each line, there are two elements:

N-gram (N is from 1 to 5)
Frequency

N-grams are sorted in the reverse order of frequency. For example, the most frequently found character in English documents is the space character (i.e., represented by '_') whose count of occurrences is 20326. From the training data, we also find that the most frequently found 2-gram is 'e_' (i.e., letter 'e' followed by a space).

Application Phase

In the application phase, the TextCat PR reads the learned model (i.e., category profiles ) and then applies the model to the data. Given a new document, first we generate a document profile (i.e., N-grams frequency profile) similar to the category profiles.

The language classification task is then to measure profile distance: For each N-gram in the document profile, we find its counterpart in the category profile, and then calculate how far out of place it is.

Finally, the bubble labelled "Find Minimum Distance" simply takes the distance measures from all of the category profiles to the document profile, and picks the smallest one.

What's in TextCat PR?

If you look inside the textcat-1.0.1.jar, you can identify the following structure:

org/
+--knallgrau/
+--utils/
 +-- textcat/
    +-- FingerPrint.java
    +-- MyProperties.java
    +-- NGramEntryComparator.java
    +-- TextCategorizer.java
    +-- textcat.conf
    +-- language_fp/
        +-- english.lm
        +-- german.lm
        +-- ...

Unfortunately, you cannot find the above source files from GATE's downloads. However, after Google search, I've found them from Google Code here.

Book Review: "Oracle Warehouse Builder 11g R2: Getting Started 2011"

2011-07-09T11:26:00.000-07:00

What's Data Warehouse

A data warehouse is a database used for reporting. The main source of the data is cleaned, transformed, cataloged and made available for use by managers and other business professionals for data mining, online analytical processing, market research and decision support (Marakas & OBrien 2009).

The data warehouse must handle large amounts of data, and must be simple to query and understand by the end users. A data warehouse maintains its functions in three layers:

Staging— used to store raw data for use by developers (analysis and support).
Integration—used to integrate data and to have a level of abstraction from users.
Access— for getting data out for users

Data Warehouse vs. Transactional Database

A data warehouse (DW) is different from a transactional database (TD). A DW is a database used for reporting where the focus is getting data out of the system. On the other hands, TD is concerned with daily operational processing where the focus is on getting data into the system.

In the design, TD uses normalized approach while DW chooses dimensional approach.

The normalized structure divides data into entities, which creates several tables in a relational database. When applied in large enterprises the result is dozens of tables that are linked together by a web of joins.

In a dimensional approach, transaction data are partitioned into either facts (actual numerical measures) and dimensions (descriptive data about those measures) that place the facts in a context that is understandable to the end-user decision maker.

In this article, we will review a book named Oracle Warehouse Builder 11g R2: Getting Started 2011, in which it addresses Oracle Warehouse Builder (i.e., one of the Oracle's data mining solutions).

Introduction of the Book

If you are new to data warehousing and need a way to get started, this book offers great help. The task of designing a data warehouse is nontrivial and you can use some helps from a good tool. On this, I agree with the author:

Oracle Warehouse Builder is a great application to use to build your warehouse.

This book provides good coverage on both the theory of data warehousing and practical ways of implementing a data warehouse that can be directly applied in the real world. It's the final product of author's 27 years' working experience in the database industry and his thorough and careful research on the Oracle Warehouse Builder.

The following books are perused and referenced by the author:

Oracle Warehouse Builder Data Modeling, ETL and Data Quality Guide
Oracle Warehouse Builder Concepts Guide
Oracle Database SQL Language Reference
Oracle Warehouse Builder Users Guide
Oracle Database Error Messages 11g Release 2(11.2)
The Data Warehouse Toolkit: The Complete Guide to Dimensional Modeling

Oracle Warehouse Builder (OWB)

The Oracle Warehouse Builder is a tool provided by Oracle, which can be used at every stage of the implementation of a data warehouse, from initial design and creation of the table structure to the extract, transform, and load (ETL) process and data-quality management.

OWB has the ability to design the objects logically using cubes and dimensions in a dimensional design. It also has the ability to implement them physically in the underlying database as either a relational structure or a dimensional structure simply by checking a box. For a relational implementation (physical implementation), OWB actually provides us two options for implementing the database:

Pure relational option
Relational OLAP option

In the Figure below, it shows OWB components and its architecture:

ACME Toys and Gizmos

In this book, a fictional organization named ACME Toys and Gizmos is used to demonstrate practical ways of implementing a data warehouse that can be directly applied in the real world. This book provides explanations throughout on how to use the Oracle Warehouse Builder tool to build a data warehouse within the context of this invented company, which is involved in storefront and online Internet sales.

For instance, a customer makes a purchase of a toy with ACME Toys and Gizmos on a particular day over the Internet, which results in a dollar amount of the transaction. The dollar amount becomes the fact and the toy purchased, the customer, and the location of the purchase (the Internet in this case) become the dimensions that provide a scope of the fact measurement and give it a meaning.

The design of the data warehouse is drawn out in a star schema configuration showing the cube, which is surrounded by the dimensions with the individual items of information (attributes) . It looks like the following:

With Star Schema, managers can easily use the data for data mining, online analytical processing, market research and decision support. For example, if a manager for ACME Toys and Gizmos needs to know what products sold well in the last quarter, the query will only involve two tables—the main fact table containing the data on number of items sold and the product dimension table that contains all the information about the product.

Summary

The purpose of this book is to introduce the Oracle Warehouse Builder and use it to design and build your first data warehouse. By following author's carefully designed components and instructions, you will easily achieve that goal.

How to Support Property Chain Axiom Using Oracle's OWL Prime

2011-06-19T13:55:00.000-07:00

In this article, we will show how to support Property Chain Axiom using OWLPrime rulebase in Oracle Semantic Technologies.

What Oracle Semantic Supports?

Oracle Semantic Technologies support the following rule set (but not limited to these):

OWLSIF (OWL with IF semantics)
- Based on Dr. Horst's pD* vocabulary
OWLPrime
OWL2RL

If you are using 11.2.0.1, you can find OWl 2 RL support in the following patch on support.oracle.com:

Patch Number 9819833 - semantic technologies 11g r2 fix bundle 2

Note that Semantic 11.2.0.2 comes with OWl 2 RL support.

Property Chain Axiom^[5]

Table 1 specifies the semantic conditions on property chain axiom:

	If	Then
prp-spo2	T(?p, owl:propertyChainAxiom, ?x) LIST[?x, ?p₁, ..., ?p_n] T(?u₁, ?p₁, ?u₂) T(?u₂, ?p₂, ?u₃) ... T(?u_n, ?p_n, ?u_n+1)	T(?u₁, ?p, ?u_n+1)

Property chain axiom allows reasoner to infer the existence of a property from a chain of properties. For example, the following hasContained semantic using property chain axiom :

hasContained(x, "EOS 60D") ^ rdf:type("EOS 60D","Digital SLR Cameras")
-> hasContained(x,"Cameras")

<rdf:description about="hasContained">
<owl:propertychainaxiom parsetype="Collection"/>
<owl:objectproperty about="hasContained"/>
<owl:objectproperty about="&rdf;type">
</owl:propertychainaxiom>
</rdf:description>

to derive the fact that an article is related to the topic "Cameras" if it contains the key words "EOS 60D" because "EOS 60D" is a rdf:type of "Digital SLR Cameras" which is, in turn, a owl:subClassOf of "Cameras". Our camera ontology example looks like this:

Using Oracle's OWLPrime rule set, it doesn't support the above inference directly. What it can infer is just:

rdf:type("EOS 60D", "Digital SLR Cameras") ^
owl:subClassOf("Digital SLR Cameras","Cameras") -> rdf:type("EOS 60D","Cameras")

However, this is different from what we want. To enable Oracle Semantic to support what we want using OWLPrime rule set, we need to:

Specify chain definition RDF triples
Specify 'CHAIN' for the inf_components_in argument in SEM_APIS.CREATE_ENTAILMENT()

Note that OWL2RL has more rules than OWLPrime does and you can use it to achieve the above task directly. However, the more rules you include in the inference, the slower performance you get. That's the reason why we document the steps here to allow users to use OWLPrime instead of OWL2RL for property chain.

Chain Definition Triples

The first requirement is to insert the necessary chain definition triples for hasContained semantic into your ontology model:

prefix prop:, namespace URI: http://xmlns.oracle.com/rdfctx/property#
prefix owl:, namespace URI: http://www.w3.org/2002/07/owl#
prefix rdf:, namespace URI: http://www.w3.org/1999/02/22-rdf-syntax-ns#

prop:hasContained  owl:propertyChainAxiom _:jA1 .
_:jA1              rdf:first              prop:hasContained .
_:jA1              rdf:rest               _:jA2.
_:jA2              rdf:first              rdf:type .
_:jA2              rdf:rest               rdf:nil .

To insert the above chain definition triples, you can use the following INSERT statements:

INSERT INTO ontology_rdf_data VALUES(ONTOLOGY_S1.nextval,
sdo_rdf_triple_s('ontology_model',
'<http://xmlns.oracle.com/rdfctx/property#hasContained>',
'<http://www.w3.org/2002/07/owl#propertyChainAxiom>',
'_:jA1'));

INSERT INTO ontology_rdf_data VALUES(ONTOLOGY_S1.nextval,
sdo_rdf_triple_s('ontology_model','_:jA1',
'<http://www.w3.org/1999/02/22-rdf-syntax-ns#first>',
'<http://xmlns.oracle.com/rdfctx/property#hasContained>'));

INSERT INTO ontology_rdf_data VALUES(ONTOLOGY_S1.nextval,
sdo_rdf_triple_s('ontology_model',
'_:jA1', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#rest>',
'_:jA2'));

INSERT INTO ontology_rdf_data VALUES(ONTOLOGY_S1.nextval,
sdo_rdf_triple_s('ontology_model','_:jA2',
'<http://www.w3.org/1999/02/22-rdf-syntax-ns#first>',
'<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>'));

INSERT INTO ontology_rdf_data VALUES(ONTOLOGY_S1.nextval,
sdo_rdf_triple_s('ontology_model',
'_:jA2', '<http://www.w3.org/1999/02/22-rdf-syntax-ns#rest>',
'<http://www.w3.org/1999/02/22-rdf-syntax-ns#nil>'));

Note that our ontology_model is created as:

-- create application table
create table ontology_rdf_data (
triple_id  NUMBER(18) NOT NULL,
triple SDO_RDF_TRIPLE_S,
CONSTRAINT ontology_rdf_data_pk PRIMARY KEY  (triple_id)
);

-- create the RDF Model --
begin
sem_apis.create_rdf_model (model_name => 'ontology_model',
table_name => 'ontology_rdf_data',
column_name => 'triple');
end;
/

SEM_APIS.CREATE_ENTAILMENT

Before you use SEM_MATCH table function to query semantic data, it is required that you create a rules index using SEM_APIS.CREATE_ENTAILMENT. The rules index will contain precomputed triples inferred from RDF model(s) and rulebase(s).

Here we describe how to set up rules index correctly for supporting property chain. First, if you have already created the rules index, drop it first:

BEGIN
SEM_APIS.DROP_ENTAILMENT('rule_index_1');
END;
/

The second step is to run inference on default graph:

exec sem_apis.create_entailment('rule_index_1',sem_models('ontology_model','model_1'),sem_rulebases('owlprime'),inf_components_in => 'CHAIN', include_default_g => sem_models('ontology_model','model_1'));

Finally, you run NG-based (i.e., Name Graph) local inference:

exec sem_apis.create_entailment('rule_index_1',sem_models('ontology_model','model_1'),sem_rulebases('owlprime'), inf_components_in => 'CHAIN', options =>'ENTAIL_ANYWAY=T,LOCAL_NG_INF=T');
commit;

Unless you specify below argument
inf_components_in => 'CHAIN'
the reasoner won't support property chain using OWLPrime rulebase.

Note that there are two RDF models used in the above global and local inference(s):

ontology_model (i.e., TBox)
model_1 (i.e., ABox)

Global Inference vs. Local Inference
Global inference takes all asserted triples from all the source model(s) provided and applies semantic rules on top of all the asserted triples till an inference closure is reached. Even if the given source models contain one more multiple named graphs, it actually makes no difference to global inference because all assertions, whether part of a named graph or not, are treated the same as if they come from a single graph.

On the other hand, local inference is performed within the boundary of every single named graph combined with the common schema. See Oracle documentation for more details.

References

Reusable ADF Components—Application Modules

2011-06-15T12:51:00.000-07:00

In the course of application development, certain components will often be reused. Creating and consuming reusable components should be included in the early design and architectural phases of software projects.

Whether the reuse happens within the same application, or across different applications, it is often advantageous to package these reusable components into a library that can be shared between different teams. These shared libraries can be added to a repository. Later if you need a component, you may look into the repository for something to be reused.

Multiple Oracle ADF components are reusable, which include^[1]:

Application modules
Business Components
Data controls
Task flows
Page templates
Declarative components

These reusable components can be packaged into the ADF Library for reuse in applications (see [4] for how-to). Creating an ADF Library JAR involves compiling the project and validating the components, creating a resource service file, control files, an adflibREADME.txt, and adding the relevant project files into a JAR.

In this article, we will discuss a specific reusable component—Application Module. Application modules are associated with Business Components. When the reusable application module was packaged, the JAR includes the Business Components used to create the application module. These components will be available for reuse.

For packaging application modules, JDeveloper adds three control files to the JAR:

oracle.adf.common.services.ResourceService.sva
Manifest.mf
adfm.xml

The service resource file for an application module includes entries for the Business Components associated with the application module, as well as an entry for the application module data control.

When you add an application module to a project, the application module appears in the Data Controls panel.

What's Application Module

Within a running BC4J application, one can think of the following containership of application objects:

Root Application Module contains nested Application Modules
An Application Module contains View Objects
A View Object contains Row Sets
A Row Set contain Row Set Iterators

Application Modules can be nested. That is, an Application Module can (logically) contain one or more other Application Modules (i.e., nested AMs) as well as View Objects. The outermost containing Application Module is referred to as the "root" Application Module.

What Do You Need to Know about Nested Application Module

In this Andrejus Baranovskis' article, it has two application modules which contain View Objects created from Employee and Job tables and are packaged into two ADF libraries

adflibEmplooyeesApp.jar
adflibJobsApp.jar

These two libraries can be imported into an ADF web application in two ways:

Integrating ADF JAR's directly into the ViewController project (i.e., using Application Modules directly from ADF JAR's)
Integrating ADF JAR's into the Model project with its own Application Module (i.e., Application Components from imported libraries are created as nested Application Modules)

Using either approach, you need to add both JAR's to the application first. When you add an ADF Library JAR to a project, either by using the Resource Palette or by manually adding the JAR, an ADF Library definition is created in the project. The ADF Library JAR file will be added to the class path of the project. The project will access and consume the components in the JAR by reference. See here for how to add an ADF Library JAR to a project using the Resource Palette.

In the first approach, two JAR's are added to the consuming project's (i.e., ViewController project) class path and so is available for reuse. See here on how to add them to the ViewController project manually. As shown below, adflibEmployeesApp.jar and adflibJobsApp.jar are added to the ViewController project's class path:
In the second approach, you first create a new Application Module (i.e., HrModule) in the Model project. See here on how-to. To specify a composite root application module that nests an instance of an existing application module, you use the overview editor for the application module. See here on how-to.

As shown below, EmpModule and JobsModule are nested under root Application Module HrModule in the second approach:
Important notes about nested application modules:

A nested Application Module design is useful for applications that define several functional

With a nested Application Module design, it is easy to re-deploy nested Application Modules as standalone Application Modules in different client applications without having to modify the metadata for the other existing Application Module.
When a root application module contains other nested application modules, they all participate in the root application module's transaction and share the same database connection and a single set of entity caches.
- This sharing is handled for you automatically by the root application module and its "Transaction" object.
A nested Application Module cannot see the instances of any other Application Modules that might be nested beneath the same root.
The API for application modules also supports nesting of application modules at runtime.
Nested Application Module can help performance by reducing database connection usage (i.e., sharing a single database connection instead of owning a separate connection per AM).

Further Considerations

You should consider how to organize and group the library JARs in a structure that fits your organizational needs. For example,
- Usually you want to have two separate application modules to support UIs and define services because
  - UI application modules may contain additional view objects and context values
    that are only required for a particular UI, but not needed by a business service.
  - Application modules that define public services are versioned, but internal UI
    application modules are not.
You should also consider creating standardized naming conventions so that both creators and consumers of ADF Library JARs can readily identify the component functionality.
- You want to try to have unique names to avoid naming conflicts with other projects, components, or connections in the application.
- Naming conflicts could arise from components created in the consuming application and those loaded from other JAR files.
A project corresponds to one ADF Library JAR.
- If you create multiple projects and want to reuse components from each of the projects, you may need to create an ADF Library JAR for each project.
You can package multiple components into one JAR file, or you can package a single component into a JAR file.
- Oracle ADF and JDeveloper give you the option and flexibility to create reusable components that best suit you and your organization.
You should avoid metadata naming conflicts between projects that will be combined at runtime.
- The basic package naming requirement is that ADF metadata registries (.dcx,.cpx, and so on) are generated based on the project's package name. So, make the package name unique.

References

Java Annotation Patterns Engine (JAPE)

2011-05-29T13:52:00.000-07:00

In this article, we will introduce the Java Annotation Patterns Engine (JAPE), a component of the open-source General Architecture for Text Engineering (GATE) platform.

Example of JAPE Grammar

See below for an example of JAPE grammar (by convention, file type of jape). And see the detailed descriptions of its components in later sections. The context under which this grammar will be executed includes:

doc —Implements gate.Document interface. JAPE rules always work on an input annotation set associated with a specific document.
inputAS —Implements gate.AnnotationSet interface and represents the input annotation set.
outputAS - Implements gate.AnnotationSet interface and represents the output annotation set.
ontology - Implements gate.creole.ontology.Ontology interface, which can be used in language analyzing.

// Valentin Tablan, 29/06/2001
// $id$


Phase:postprocess
Input: Token SpaceToken
Options: control = appelt debug = true

// CR+LF | CR |LF+CR -> One single SpaceToken
Rule: NewLine
(
({SpaceToken.string=="\n"}) |
({SpaceToken.string=="\r"}) |
({SpaceToken.string=="\n"}{SpaceToken.string=="\r"}) |
({SpaceToken.string=="\r"}{SpaceToken.string=="\n"})
):left
-->
{
gate.AnnotationSet toRemove = (gate.AnnotationSet)bindings.get("left");
outputAS.removeAll(toRemove);
//get the tokens
java.util.ArrayList tokens = new java.util.ArrayList(toRemove);
//define a comparator for annotations by start offset
Collections.sort(tokens, new gate.util.OffsetComparator());
String text = "";
Iterator tokIter = tokens.iterator();
while(tokIter.hasNext())
text += (String)((Annotation)tokIter.next()).getFeatures().get("string");

gate.FeatureMap features = Factory.newFeatureMap();
features.put("kind", "control");
features.put("string", text);
features.put("length", Integer.toString(text.length()));
outputAS.add(toRemove.firstNode(), toRemove.lastNode(), "SpaceToken", features);
}

What's JAPE?

JAPE is a finite state transducer that operates over annotations based on regular expressions. Thus it is useful for pattern-matching, semantic extraction, and many other operations over syntactic trees such as those produced by natural language parsers.

A JAPE grammar consists of a set of phases, each of which consists of a set of pattern/action rules. The phases run sequentially and constitute a cascade of finite state transducers over annotations. One of the main reasons for using a sequence of phases is that a pattern can only be used once in each phase, but it can be reused in a later phase.

Input annotations could be specified at the beginning of the grammar. This specifies what types of annotations will be processed by the rules of grammar. Other not-mentioned types will be ignored. By default the transducer will include Token, SpaceToken and Lookup.

Options specification defines the method of rule matching (i.e., control) and debug flag for the rules (i.e., debug) in the grammar. There are five control styles:

brill — When more than one rule matches the same region of the document, they all are fired.
all — Similar to brill, in that it will also execute all matching rules, but the matching will continue from the next offset to the current one.
first — With the first style, a rule fires for the first match that‘s found.
once — Once a rule has fired, the whole JAPE phase exits after the first match.
appelt — Only one rule can be fired for the same region of text, according to a set of priority rules. The appelt control style is the most appropriate for named entity recognition as under appelt only one rule can fire for the same pattern.

If debug is set to true, any rule-firing conflicts will be displayed in the messages window if the grammar is running in appelt mode and there is more than one possible match.

Following the declaration portions of grammar, a list of rules are specified. Each rule consists of a left-hand-side (LHS) and a right-hand-side (RHS). The LHS of the rules consists of an annotation pattern description. The RHS consists of annotation manipulation statements. Annotations matched on the LHS of a rule may be referred to on the RHS by means of labels that are attached to pattern elements.

LHS

LHS contains annotation pattern that may contain regular expression operators e.g. ("+", "?" , "*"). However, you should avoid the use of “*” based regular expressions for better performance.

There are 3 main ways in which the pattern can be specified:

As a string of text
- e.g., {Token.string == "Oracle"}
- This pattern matches a string of text with the value of "Oracle".
As the attributes (and values) of an annotation
- e.g., ({Token.kind == word, Token.category == NNP, Token.orth == upperInitial})?
- The above pattern uses the Part of Speech (POS) annotation where kind=word, category=NNP and orth=upperInitial.
As an annotation previously assigned from a gazetteer, tokeniser, or other module
- ({Company})?:c1 ({Positives}):v ({Company})?:c2 ({Split}|{CC})?
- The above pattern matches annotations of Company type, followed by annotations of Positives type, etc. The first-matched pattern element is labeled as c1, the second-matched pattern element is labeled as v, etc.

There are different kind of operators supported:

Equality operators (“==” and “!=”)
- {Token.kind == "number"}, {Token.length != 4}
Comparison operators (“<”, “<=”, “>=” and “>”)
- {Token.string > "aardvark"}, {Token.length < 10}
Regular expression operators (“=~”, “==~”, “!~” and “!=~”)
- {Token.string =~ "[Dd]ogs"}, {Token.string !~ "(?i)hello"}
- ==~ and !=~ are also provided, for whole-string matching
{X contains Y} and {X within Y} for checking annotations within the context of other annotations

You can even define custom operators by implementing gate.jape.constraint.ConstraintPredicate.

RHS

The right-hand-side (RHS) consists of annotation manipulation statements. For example, you can add/remove/update annotations associated with a document. Alternatively, RHS can contain Java code to create or manipulate annotations. In this article, we will focus only on RHS' implemented in Java code.

On the RHS, Java code can reference the following variables (which are passed as parameters to the RHS action):

doc
bindings
annotations
inputAS
outputAS
ontology

annotations is provided for backward compatibility and should not be used for new implementations. inputAS and outputAS represent the input and output annotation set. Normally, these would be the same (by default when using ANNIE, these will be the “Default” annotation set) . However, the user is at liberty to change the input and output annotation sets in the parameters of the JAPE transducer at runtime. Therefore, it cannot be guaranteed that the input and output annotation sets will be the same, and we should specify the annotation set we are referring to.

Annotations matched on the LHS of a rule may be referred to on the RHS by means of labels that are attached to pattern elements. They can be retrieved by using bindings as follows:

gate.AnnotationSet toRemove = (gate.AnnotationSet)bindings.get("c1");

This returns a temporary annotation set which holds all the annotations matched on the LHS that have been labeled as "c1."

In the following discussions, we assume you use ANNIE and both inputAS and outputAS points to the same annotation set.

On the RHS, you can do any of the following:

Remove annotations from document's annotation set(s)
Update annotations in document's annotation set(s)
Add new annotations to document's annotation set(s)

However, if you try to remove annotations while using the same iterator for other tasks at the same time, you may see:

java.util.ConcurrentModificationException

The solution is to collect all to-be-removed annotations on a list and process them at the end.

RhsAction

To understand the RHS action, you need to know how a JAPE rule is translated to its executable binary in Java. For example, rule ConjunctionIdentifier2

Rule: ConjunctionIdentifier2
(
({Token.category=="CC"}):conj2
)
-->
:conj2
{

gate.AnnotationSet matchedAnns= (gate.AnnotationSet) bindings.get("conj2");
gate.FeatureMap newFeatures= Factory.newFeatureMap();
newFeatures.put("rule","ConjunctionIdentifierr21");
outputAS.add(matchedAnns.firstNode(),matchedAnns.lastNode(),"CC", newFeatures);
}

will be translated into:

1  // ConjunctionIdentifierConjunctionIdentifier2ActionClass14
2  package japeactionclasses;
3  import java.io.*;
4  import java.util.*;
5  import gate.*;
6  import gate.jape.*;
7  import gate.creole.ontology.*;
8  import gate.annotation.*;
9  import gate.util.*;
10
11  public class ConjunctionIdentifierConjunctionIdentifier2ActionClass14
12  implements java.io.Serializable, RhsAction {
13    public void doit(gate.Document doc,
14                     java.util.Map bindings,
15                     gate.AnnotationSet annotations,
16                     gate.AnnotationSet inputAS, gate.AnnotationSet outputAS,
17                     gate.creole.ontology.Ontology ontology) throws gate.jape.JapeException {
18      gate.AnnotationSet conj2Annots = bindings.get("conj2");
19      if(conj2Annots != null && conj2Annots.size() != 0) {
20
21
22      gate.AnnotationSet matchedAnns= (gate.AnnotationSet) bindings.get("conj2");
23      gate.FeatureMap newFeatures= Factory.newFeatureMap();
24      newFeatures.put.("rule","ConjunctionIdentifierr21");
25      outputAS.add(matchedAnns.firstNode(),matchedAnns.lastNode(),"CC", newFeatures);
26
27      }
28    }
29  }

Notice that RHS of the rule is wrapped into doit method which has the following signature:

public void doit(gate.Document doc,
java.util.Map bindings,
gate.AnnotationSet annotations,
gate.AnnotationSet inputAS, gate.AnnotationSet outputAS,
gate.creole.ontology.Ontology ontology)

That's why you can reference:

doc
bindings
annotations
inputAS
outputAS
ontology

without declaring them.

Also notice that the return type of doit method is void. It means that you can exit from the middle of action execution by issuing a return statement:

if (annotation.getFeatures().get("tagged") != null)
return;

References

Cannot get GATE Home. Pease set it manually!

2011-05-25T11:21:00.000-07:00

When you run your application using GATE Embedded, you often run into an error:

Cannot get GATE Home. Pease set it manually!

This means that you need to set gate.home property before calling Gate.init(). You can do that in two ways:

In your Java code
- Gate.setGateHome(File)
In the Java command that launches your program

-Dgate.home=path/to/gate/home

GATE also needs to initialize the paths to local files of interest like:

Installed plugins home
Site configuration file
User configuration file

if these are not at their default locations. To help configure these paths, you can use the following system properties:

gate.home: sets the location of the GATE install directory. This should point to the top level directory of your GATE installation. This is the only property that is required. If this is not set, the system will display an error message and them it will attempt to guess the correct value.
gate.plugins.home: points to the location of the directory containing installed plugins (a.k.a. CREOLE directories). If this is not set then the default value of {gate.home}/plugins is used.
gate.site.conﬁg: points to the location of the conﬁguration ﬁle containing the site-wide options. If not set this will default to {gate.home}/gate.xml. The site conﬁguration ﬁle must exist!
gate.user.conﬁg: points to the ﬁle containing the user’s options. If not speciﬁed, or if the speciﬁed ﬁle does not exist at startup time, the default value of gate.xml (.gate.xml on Unix platforms) in the user’s home directory is used.
load.plugin.path: is a path-like structure, i.e. a list of URLs separated by ‘;’. All directories listed here will be loaded as CREOLE plugins during initialisation. This has similar functionality with the the -d command line option.
gate.builtin.creole.dir: is a URL pointing to the location of GATE’s built-in CREOLE directory. This is the location of the creole.xml ﬁle that deﬁnes the fundamental GATE resource types, such as documents, document format handlers, controllers and the basic visual resources that make up GATE. The default points to a location inside gate.jar and should not generally need to be overridden.

As described above, the only property that is required is gate.home if you lay out other resources at their default locations.

In this article, we will show you one way to run your GATE application in Oracle WebLogic Server (WLS). This allows you to test your deployed application quickly.

Classloading in Java Platform and Oracle WebLogic Server

If the application you are creating has dependencies on some third-party code (for example, gate.jar), what is the proper way to package these libraries so that they can be used by a portable J2EE application?

In the J2EE platform, there are mechanisms^[4] available for including libraries in a portable application:

The WEB-INF/lib Directory
Bundled Optional Classes
Installed Packages (or installed optional packages mechanism)

Since these mechanisms are well-documented, they will not be repeated here.

To use these third-party libraries along with your application code, you face the decision of which packaging mechanism to choose. The decision you make can have major effects on the following:

The portability of your application
The size of your WAR and EAR files
The maintenance of the application
Version control as libraries and application servers are updated

Some solutions for packaging library JAR files are specific to a particular application server: for example, placing a library JAR file in an application server's classpath so that applications can use the APIs in that JAR file. Some application servers have container-specific locations where you can place JAR files to be shared by applications and modules. But these mechanisms are not portable, unlike the mechanisms provided by the J2EE platform.

In this article, we will introduce one WLS-specific mechanism to use for the GATE installation. This will allow you to quick-test your GATE application.

In WLS, you can place JAR files to be shared by applications and modules at the following location:

$DOMAIN_DIR/lib

This is the domain library directory. The domain library directory is one mechanism that can be used for adding application libraries to the server classpath. The jars located in this directory will be picked up and added dynamically to the end of the server classpath at server startup. The jars will be ordered lexically in the classpath.

It is possible to override the $DOMAIN_DIR/lib directory using the -Dweblogic.ext.dirs system property during startup. This property specifies a list of directories to pick up jars from and dynamically append to the end of the server classpath using java.io.File.pathSeparator as the delimiter between path entries.

Default GATE Installation Layout

The GATE architecture is based on components. Each component (i.e., a Java Beans), is a reusable chunks of software with well-defined interfaces that may be deployed in a variety of contexts.

You can define applications with processing pipelines using these reusable components. In GATE, these resources are officially named CREOLE (i.e., Collection of REusable Objects for Language Engineering). You can read this article to understand how GATE plugins and CREOLE resources are configured.

In the following, we show how GATE's resources are laid out in the WLS' domain library directory:

/wls_domain/lib/gatehome (i.e., GATE's home directory)
+-- lib/
+-- Bib2HTML.jar
+-- GnuGetOpt.jar
+-- ...
+-- plugins/
+-- ANNIE/
  +-- ANNIE_with_defaults.gapp
  +-- build.xml
  +-- creole.xml
  +-- resources/
+-- Tools/
  +-- build.xml
  +-- creole.xml
  +-- doc/
  +-- resources/
  +-- src/
  +-- tools.jar
+-- gate .xml

After you've installed GATE's libraries and resources in the domain library directory. The next step you need to do is setting gate.home property in wls_domain/bin/setDomainEnv.sh:


EXTRA_JAVA_PROPERTIES=" ${EXTRA_JAVA_PROPERTIES} -Dweblogic.security.SSL.ignoreHostnameVerification=true -Dgate.home=${DOMAIN_HOME}/lib/gatehome"
export EXTRA_JAVA_PROPERTIES

Final Words

As mentioned before, this is not the best way to configure GATE's installation in a WLS. However, this approach will allow you to test your deployed GATE application quickly on it.

The domain library directory in WLS is intended for JAR files that change infrequently and are required by all or most applications deployed in the server, or by WebLogic Server itself. For example, you might use the lib directory to store third-party utility classes that are required by all deployments in a domain. You can also use it to apply patches to WebLogic Server.

The domain library directory is not recommended as a general-purpose method for sharing a JARs between one or two applications deployed in a domain, or for sharing JARs that need to be updated periodically. If you update a JAR in the lib directory, you must reboot all servers in the domain in order for applications to realize the change. If you need to share a JAR file or Java EE modules among several applications, use the Java EE libraries feature here. Alternatively, you can write custom class loaders to better fit your application's needs.

References

Configuring JDBC Data Sources in JDeveloper and Oracle WebLogic Server

2011-05-24T14:52:00.000-07:00

In a previous article, we have introduced different ways of creating and managing database connections in JDeveloper. Those connections (i.e. using JDBC URL) are good for the testing of JDeveloper Design-time, Business Components Tester, and Integrated WebLogic Server.

In the production environment, the web application would typically reference a JDBC datasource, since it simplifies maintenance of the connection credentials by allowing them to be centrally managed in the Java EE container. In this article, we will show you how to:

Switch from JDBC URL to JDBC DataSource in JDeveloper.
Setup global JDBC DataSource for database connection in the WebLogic Server
Deploy a Web Application to the WebLogic Server

JDBC URL vs. JDBC DataSource

If you use JDBC URL connection type, you provide settings as shown below:
However, if you use JDBC DataSource connection type, its settings are done on the server. To avoid passwords being present in plain text in deployed files, JDeveloper uses password indirection, which means that passwords for the data sources must be set on the server before the application will run correctly.

A data source object enables a Java Database Connectivity (JDBC) client to obtain a DBMS connection from a JDBC pool. A data source is a vendor-independent encapsulation of a database server connection. The data source offers advantages over a JDBC URL connection because the data source can be tuned, reconfigured, or remapped without changing the deployed application.

In WebLogic Server, you configure database connectivity by adding data sources to your WebLogic domain. WebLogic JDBC data sources provide database access and database connection management. Each data source contains a pool of database connections that are created when the data source is created and at server startup.

Choosing JDBC DataSource

After you finish testing your application using Integrated WebLogic Server and decide to deploy it to a standalone WebLogic Server, then it's time to configure JDBC DataSource as your application's connection type.

This configuration step is done on the Application Module in the Business Layer.
Edit Business Components Configuration dialog is used to create a new application module configuration or edit an existing one. To open it, do:

Application Navigator context menu for application modules > Configurations > Edit > Application Module tab

You choose to connect to a JDBC DataSource from the dropdown list. The JDeveloper helps create the data source name based on available resource connections. This data source naming convention follows the Java EE standard which specifies that resource connections appear in the application-specific name space java:comp/env/jdbc/. For example, for a connection named 'SmmApp', the JDBC Datasource name would be 'java:comp/env/jdbc/SmmAppDS'.

When you deploy the application and run it in standalone Oracle WebLogic Server, the specified data source connection in the application module configuration will be used.

Setting up Global JDBC DataSource

You can create a global data source on Oracle WebLogic Server Administration Console:

http://xbox.mycompany.com:7001/console/

To set up a global data source:

Login to the Oracle WebLogic Server Administration Console. Click on the Data Sources link under JDBC. On the Summary of JDBC Data Sources page, click New. In the Create a New JDBC Data Source page, enter details of the data source.
The name can be anything.
The JNDI name must be of the form jdbc/connection-nameDS. For example, if the application has a connection name SmmApp, the JNDI name is jdbc/SmmAppDS. Ensure that the database type is Oracle and that the driver is Oracle’s Driver (Thin) for Service Connections;Version 9.0.1,9.2.0,10,11. Click Next twice to navigate to the Create a New JDBC Data Source page, where you enter the connection details.
The database name is the Oracle SID.
The host name is the the name of the machine the database is on.
The default port is 1521.
Enter the user name and password, for example hr/hr. Click Next and click Test Configuration. Click Next to navigate to the Select Targets page, where you select a target for this data source. If you fail to select a target, the data source is created but not deployed. Click Finish.

Steps to Deploy to WebLogic Server

Application Properties Dialog is used to to define the deployment profiles that will be available to an application. To open Deployment page, do:

Application menu > Application Properties > Deployment page

Makre sure "Auto Generate and Synchronize weblogic-jdbc.xml Descriptors During Deployment" is unchecked. When this field is not selected, this means that your deployed application will use global data sources on the server.
You can also edit the default deployment profile (i.e. SmmTest_application1--EAR File) or create a new one if needed.

There are two options for the deployment:

Deployed to Ear
Deployed to Application Server

If you want to deploy your application directly to the server, configure Resource Palette with a new Application Server Connection (i.e., xbox) as follows:
You then deploy your application using context menu. Right select your application and select Deploy. Choose the destination to be your application server (i.e., xbox).

References

Exposing List Model Instance as Table Component in Oracle ADF

2011-05-17T14:19:00.000-07:00

Oracle ADF is based on the Model-View-Controller (MVC) design pattern. Separating applications into these layers simplifies maintenance and reuse of components across applications.
The Task

In this article, we will show how to create a table component (i.e., af:table) using a custom method in the Application Module. This custom method returns a List instance whose items will be displayed as rows in the table.

Here af:table exists in the View layer. Our custom method which provides table contents exists in the Business layer. This custom method is exposed on the client interface of an Application Module and exported to the Model layer as data control and binding object.

In this article, we will show how to achieve this. Before you start, read this companion article first.

The Background

The Table component uses a model to access the data in the underlying list. The specific model class is oracle.adf.view.rich.model.CollectionModel. You may also use other model instances, e.g., java.util.List, array, and javax.faces.model.DataModel. The Table will automatically convert the instance into a CollectionModel.

Normally, you would create table using ADF View Object which is exported to the Model layer. You create an ADF bound ADF Faces table by dragging a collection from the ADF Data Controls panel to a page or page fragment. Using this approach, you can get access to its CollectionModel easily. However, for some cases, creating a View Object can be difficult. For example, our query using Oracle Semantic Technology doesn't allow us to use bind variable.

select  postab.post_id, postab.content_value
from table(sem_match('(?s <http://xmlns.oracle.com/rdfctx/property/hasXxxOf>   <http://xmlns.oracle.com/rdfctx/organization/oracle>)',
  sem_models('smm_vpd_model_1','smm_ontology_model'),
  sem_rulebases('owlprime'), null, null))  graph,
  smm.smm_vpd_rdf_data_1 app,
  smm.smm_posts postab
where app.triple.rdf_p_id=oracle_orardf_res2vid('http://xmlns.oracle.com/rdfctx/property/hasXxxOf')
  and app.triple.rdf_c_id=oracle_orardf_res2vid('http://xmlns.oracle.com/rdfctx/organization/oracle')
  and graph.s$RDFVID=app.triple.rdf_s_id
  and postab.post_id=app.post_id
;

Ideally, we would like to make object in the RDF triple a bind variable. Since sem_match is an operator and doesn't allow that. The workaround will be creating a custom method which returns a List instance. Within the method, we create a custom query statement based on the name of an object (i.e., "oracle"). The signature of the custom method will be:

public List<postobj> positivePostsByBrand(String brandName) {
}

The Steps

Because of dependencies, we will work from Business Layer back to View Layer. All Fusion Web Applications are created with two projects:

Model
ViewController

For step 1 below, we will work in the Model project. For other steps, we will work in the ViewController project.

Step 1: Add Custom Method to the AM

Add our custom method (i.e., positivePostsByBrand) to the Application Module:
Shuttle custom method from the available list to the selected list:
In the Data Controls panel, you should find the new custom method listed under your application module.

Step 2: Create MethodAction Binding Object

Select the JSF page to which you want to add the new table. In its Bindings view, create a new binding object using the new data control object (i.e. our custom method positivePostsByBrand). By default, the binding objects are named after the data control object that was used to create it.
Our new binding object will be methodAction (under Generic Bindings) item type:

On Create Action Binding, select your AM (i.e., SemAppModuleDataControl). No, don't expand its contents. Look underneath for an Operation drop-down list. Select your custom method. Take a note of the name of its parameter (i.e., brandName) which you need to use later.
Step 3: Create a New Getter Method on a Managed Bean

We need a getter method on a managed bean, which will fetch table contents on behave of View layer. For this exercise, we have created a managed bean named ActionBean which it has been registered on the ADF's unbounded task flow (i.e., adfc-conf.xml):

This managed bean has a session scope. Our getter method in ActionBean.java looks like this:

public List<PostObj> getPositivesByBrand() {
  if (getBrandName() == null || getBrandName().length() == 0)
    return new ArrayList<PostObj>();
  else {
    OperationBinding oper = getOperBindings("positivePostsByBrand")  ;
    Map params = oper.getParamsMap();
    params.put("brandName", brandName);
    oper.execute();
    return (List<PostObj>)oper.getResult();
  }
}

Within it, it uses a binding object named positivePostsByBrand to fetch table contents from the business layer (i.e., via our custom method defined in the Application Module implementation file). To execute our custom method, we also need a parameter named brandName. We will discuss how to provide this parameter at runtime later.

Step 4: Create New Table on JSF Page

Select the component (i.e., af:panelHeader) that you want to insert the new table to and insert a new ADF Faces component (i.e., af:table):
On Insert ADF Faces Item, select Table:
On Create ADF Faces Table, check Bind Data Now and click Browse...:
You will find our variable named positivesByBrand (i.e., exposed by the getter method) under ADF Managed Bean > actionBean. Select it and an EL will be created automatically for you.
Next we will create new columns mapped to the properties of the List instance object (i.e., PostObj). Click New:
Add new columns as shown. Their values will be mapped to the property's on our List instance object (i.e.,PostObj).
The Missing Link

As noted above, to execute the custom method we need a parameter (i.e., brandName). To provide that, we need to dynamically select that name from the UI. For example, in a master table, you may display rows with different brand name on each row. The brand name (or the count in our case) can then be implemented as an af:commandLink:

<af:commandLink  id="cl1" actionListener="#{actionsBean.positivePostsByBrand}">
  <af:outputText value="#{row.count}" id="ot5"/>
  <f:attribute name="posBrandName" value="#{row.brand}"/>
</af:commandLink>

Upon clicking, it will dispatch an ActionEvent which will be consumed by a listener (i.e., positivePostsByBrand method on our managed bean). Within the method, it will retrieve an attribute named posBrandName from the event's source object as such:

public void positivePostsByBrand( ActionEvent actionEvent){
  RichCommandLink _table = (RichCommandLink) actionEvent.getSource();
  String brandName = (String) _table.getAttributes().get("posBrandName");
  // set brand name to be used in getPositivesByBrand method
  setBrandName(brandName);
  getPositivesByBrand();
}

Note that attribute posBrandName will be set to be:

#{row.brand}

as defined in the af:commandLink.

References

Diagnosing Java.lang.OutOfMemoryError

2011-05-15T08:39:00.000-07:00

When I ran my application, it threw the following exceptions:

java.lang.OutOfMemoryError: GC overhead limit exceeded^[7,9]
java.lang.OutOfMemoryError: Java heap space

The first message means that, for some reason, the garbage collector is taking an excessive amount of time and recovers very little memory in each run. After I removed the following statement:

System.gc();

The 1st message was gone. However, the system threw the 2nd message. So, obviously my heap space issue remains. Here are the steps that I took to investigate it:

Add the following Java Options
- -Xloggc:gc.log -XX:+PrintGCDetails -XX:+PrintGCTimeStamps
  - System will generate a gc.log file
- -XX:+HeapDumpOnOutOfMemoryError
  - System will generate a heap dump file
Analyze the log files:
- Use regular text editor to examine gc.log file
- Use Eclipse Memory Analyzer to examine heap dump file (i.e., java_xxx.hprof)

Note that all command options discussed in this article applied to Hotspot VM.

JVM Options

The command line options specify:

-XX:+PrintGCDetails
- prints more details at garbage collection.
-XX:+PrintGCTimeStamps
- prints a time stamp representing the number of seconds since the HotSpot VM was launched until the garbage collection occurred.
-Xloggc:gc.log
- causes information about the heap and garbage collection to be printed at each collection.

To set Java Options in JDeveloper, do the following:

Right select your project (i.e., ViewController) and bring up the context menu
Select Project Properties...
Select Run/Debug/Profile
Select your Run Configuration (i.e., Default)
Click Edit button
Specify -Xloggc:gc.log -XX:-PrintGCDetails in the Java Options field

Run your application and reproduce the out-of-memory exception. A log file named gc.log will be generated. I've found mine in the following location:

.../system11.1.1.5.37.60.13/DefaultDomain

because my web application was deployed to the Integrated WLS^[4] and run from DefaultDomain. To understand the format of gc.log, read [5] for details.

However, gc.log file was not really helpful because it simply pointed out there was a heap issue. But, it didn't say where.

The next step I have taken is running my server with the following flag:

-XX:+HeapDumpOnOutOfMemoryError

it generated a java_pid30835.hprof file when my server encountered a heap error.

Eclipse Memory Analyzer

The heap dump file (i.e., java_pid30835.hprof) is generated by HPROF—a heap and cpu profiling tool. My heap dump file was generated in binary format. Therefore I need to use Eclpse Memory Analyzer to examine it.

You can install Eclipse MAT via the Eclipse Update manager . Select "General Purpose Tools " and install "Memory Analyser (Incubation)" and "Memory Analyser (Charts)".
After installation, double-click your heap dump file and select "Leak Suspects Report".
Eclipse MAT will show a diagram:
and problem suspects:
You can click on the "Details" link to investigate.

Heap Size Adjustment

If you observe an OutOfMemoryError in the garbage collection logs, try increasing the Java heap size to 80% to 90% of the physical memory you have available for the JVM. Based on whether the old generation space or the permanent generation space is running out of memory, you adjust the sizes of heap spaces in this way^[10]:

For old generation space OutOfMemoryErrors

increase -Xms and -Xmx

For permanent generation OutOfMemoryErrors

increase -XX:PermSize and -XX:MaxPermSize

References

Eclipse Update Manager
Eclipse Memory Analyzer
Java Hotspot VM Options
Integrated WebLogic Server (WLS)
Diagnosing a Garbage Collection problem
Frequently Asked Questions about Garbage Collection
GC Overhead Limit Exceeded
HPROF: A Heap/CPU Profiling Tool in J2SE 5.0
Java SE 6 HotSpot[tm] Virtual Machine Garbage Collection Tuning
Java Performance by Charlie Hunt and Binu John
Understanding Garbage Collection
Java HotSpot VM Options
GCViewer (a free open source tool)

Invoking Application Module Custom Methods from Oracle ADF Frontend—Why and How?

2011-05-01T13:30:00.000-07:00

In an Oracle Fusion web application, you should use managed beans^[4] to store logic that is related to the UI rendering only. All application data and processing should be handled by logic in the business layer of the application.

In this article, we'll show how to refresh a calculated attribute^[6] named Total Comments after user adds a new comment using Create Comment Dialog. As noted above, refreshing Total Comments should be handled in ADF backend (i.e., ADF Business Components), not ADF frontend (i.e., ADF Faces). Note that ADF backend refers to Model project and ADF frontend refers to ViewController project in a Fusion web application.

Background Information

In the described application, we have two view objects (i.e., TestVO and TestCommentVO) with master-detail relationship. "TotalComments" on the TestVO is a calculated attribute which computes total number of chronological comments (represented by TestCommentVO) added to a test.

On the Test View page, it displays Total Comments column which is also a link. By clicking on the link, user can navigate to the Test Comment page. On the Test Comment page, user is allowed to add new comments. After adding new comments, the Total Comments column on the original Test View page need to reflect the new total.

The Task

To achieve this task, we need to invoke a custom method implemented in ADF Business Components from the Test Comment component implemented in ADF Faces. Method invokation is triggered when user clicks the Save and Close button to save the newly created comment.

The bridge provided between ADF frontend and ADF backend is the Data Binding Layer in Fusion web application^[3]. ADF data-binding layer implements the Data Controls and Bindings from JSR-227. The data controls abstract the back-end business service implementations and binding objects link front-end user interface controls in a declarative way to back-end data.

The steps of the task ordered from backend (in blue) to frontend (in black) are summarized here:

Creating a custom method named refreshTotalComments in the application module Class (i.e., SelTestPortalAMImpl.java).
Exporting refreshTotalComments by including the method on the application module's UI client interface.
Adding a new action binding^[5] named refreshTotalComments on TestCommentPageDef.xml.
Creating a managed bean named TestCommentBean.java with a method action named saveAndClose. In the method, it will retrieve and execute refreshTotalComments operation binding.
Registering new managed bean in adc-config.xml with the scope of request.
Linking method action saveAndClose on the managed bean to the actionlistener of Save and Close button.

In the following sections, we'll describe those steps in details.

Step 1 — Adding Custom Method to the AppModuleImpl File

To add a custom service method (i.e., refreshTotalComments) to your application module, you must generate the application module class files first.

To generate Java files for your application module class:

In the Application Navigator, double-click the application module.
In the overview editor, click the Java navigation tab and click the Edit java options button.
In the Select Java Options dialog, select Generate Application Module Class.
Click OK.

In SelTestPortalAMImpl.java file, you add your custom service method — refreshTotalComments. Here we have left out the details of refreshTotalComments. For ADF developers need to write a custom method such as refreshTotalComments, you can read this document. It provides a high-level description of the key ADF Business Components classes in the Oracle Application Development Framework and it summarizes the methods that ADF developers write, call, and override most frequently.

Step 2 — Publishing Custom Method on the Application Module’s Client Interface

To include a public method from your application module's custom Java class on the client interface, use the Java Classes page of the overview editor for the application module, and then click the Edit icon in the Client Interface section of the page to display the Edit Client Interface dialog. Select method refreshTotalComments from the Available list and click the Add button to shuttle them into the Selected list. Then click OK to close the editor.

You can include any custom method in the client interface that obeys these implementation rules:

If the method has a non-void return type, the type must be serializable (i.e., implements the java.io.Serializable interface).
If the method accepts any parameters, all their types must be serializable.
If the method signature includes a throws clause, the exception must be an instance of JboException in the oracle.jbo package.

Step 3 — Adding a New Action Binding

In the ViewController project, select Test Comment page and right click it. From the context menu, select "Go to Page Definition." This will bring you to the TestCommentPageDef.xml.

In the Overview editor for the Test Comment page definition’s Bindings and Executables tab, click the Add icon in the Bindings section. Then, follow these steps:

In the Insert Item dialog, select methodAction and click OK.
In the Create Action Binding dialog:
- Select the data collection (i.e., SelTestPortalAMDataControl) where you have created your handler.
- From the Operation dropdown list, select the handler (i.e., refreshTotalComments).
- Click OK.

Step 4 — Creating a New Managed Bean

In the ViewController project, create a managed bean named TestCommentBean.java with a method action named saveAndClose as shown below.

public void saveAndClose(ActionEvent actionEvent) {
try{
// Commit the transaction
OperationBinding  oper = getOperBindings("Commit");
oper.execute();
// refresh total comments
oper = getOperBindings("refreshTotalComments");
oper.execute();
}catch(Exception e){
e.printStackTrace();
}
}
/**
* This methos returns the operation bindings of the passed method name
* @param operation name
* @return
*/
private OperationBinding getOperBindings(String operation) throws Exception
{
OperationBinding oper=null;

try
{
FacesContext facesContext = FacesContext.getCurrentInstance();
ExpressionFactory exp = facesContext.getApplication().getExpressionFactory();
DCBindingContainer bindingContainer =
(DCBindingContainer) exp.createValueExpression(facesContext.getELContext(),
                                      "#{bindings}",
                                       DCBindingContainer.class).getValue(facesContext.getELContext());
// A ControlBinding that binds an datacontrol action, including navigational
// actions such as "Next" and "Prev", or other actions such as "Commit" and
// "Rollback", to a view component.
oper = bindingContainer.getOperationBinding(operation);
}
catch(Exception e)
{
e.printStackTrace();
}
return oper;
} //end getOperBindings

As shown in the code, we need to retrieve two operation bindings (i.e., Commit and refreshTotalComments) from the binding container^[7]. Operation binding refreshTotalComments is used at runtime to invoke our Application Module custom method.

Step 5 — Registering New Managed Bean in adc-config.xml

As a general rule for Fusion web applications, a bean that may be used in more than one page or task flow, or one that is used by pages within the main unbounded task flow (adfc-config), should be registered in the adfc-config.xml configuration file.

To register TotalCommentBean in adc-config.xml, do the following:

In the Application Navigator, double-click the adfc-config.xml file in theWEB-INF folder.
In the editor window for the adfc-config.xml file, click the Overview tab.
In the Managed Beans page, in the Managed Beans section click the Add icon and enter TotalCommentBean as the name of the bean, enter the fully qualified class name, and select request scope^[8].

Step 6 — Linking Method Action to the ActionListener of Button

The final step is to link method action saveAndClose on the managed bean to the actionListener of Save and Close button as shown below:

<af:commandbutton id="FAsc1"
textandaccesskey="#{applcoreBundle.SAVE_AND_CLOSE}"
shortdesc="#{applcoreBundle.SAVE_AND_CLOSE_SHORT_DESC}"
actionlistener="#{TestCommentBean.saveAndClose}">
</af:commandbutton>

Note that you can achieve this linking declaratively using Property Inspector.

The Explanation

An application module can expose its data model of view objects to clients without requiring any custom Java code. This allows client code to use the ApplicationModule, ViewObject, RowSet, and Row interfaces in the oracle.jbo package to work directly with any view object in the data model.

Whenever there is a need to provide custom codes as shown in our sample application, you should encapsulate the details by writing a custom method in your application module's Java class.

When working with Fusion web applications using the ADF Model layer for data binding, JDeveloper configures a servlet filter in your user interface project (i.e., ViewController) called the ADFBindingFilter. It orchestrates the automatic acquisition and release of an appropriate application module instance based on declarative binding metadata, and ensures that the service is available to be looked up as a data control using a known action binding or iterator binding, specified by any page definition file in the user interface project.

At runtime, you can access the application module's client interface from the DCBindingContainer by naming an ADF action binding or an ADF iterator binding (see step 4). You can also reference the binding context^[7] and call methods on the custom client interface in any JSF managed bean.

Reference(s)

Integrated WebLogic Server (WLS)

2011-04-26T21:42:00.000-07:00

To run JDeveloper application in a Java EE container, it must be bound to a Server Instance. Integrated WebLogic Server (Integrated WLS) comes packaged with JDeveloper. Testing JDeveloper applications on Integrated WLS Server is easy because:

Deployment is optimized and the requirement to zip and copy files is eliminated.
Most files run directly from project directories. This feature enables you to make selected changes and refresh these changes while the application is running. For example, any changes made to a JSPX page can be refreshed immediately, without redeploying the application.
There is no requirement to undeploy applications after testing and debugging. Applications are undeployed when the Default Server becomes unavailable.
JDeveloper enables you to quickly create test users and passwords to test security in Integrated WLS.

Integrated WLS

You can run your applications directly on Integrated WebLogic Server without the need to deploy. The integrated WLS is sufficient to run your application to make sure it displays correctly in browsers, or for testing and debugging portions of the application. However, real end-to-end testing should be done in a standalone Administration Server because that is what will be used in a production environment.

JDeveloper is bundled with a WLS domain, and "DefaultServer" is defined for it. All JDeveloper applications are bound by default to "DefaultServer." In this document, these default settings are assumed. To view the properties of "DefaultServer" Server Instance, in the Application->Application Properties...->Run panel, select "Application Server Properties".

Alternatively, you can view the properties of IntegratedWebLogicServer from the Application Server Navigator:

If necessary, open the Application Server Navigator by choosing View->Application Server Navigator.
Right-click the IntegratedWebLogicServer connection and choose Properties.

DefaultDomain

"DefaultDomain" is bundled with JDeveloper. If you have not explicitly created Integrated WebLogic Server's default domain, it will automatically be created with default settings when you start the server by running or debugging an application. The default domain and its associated default server is located here:

$JDEV_USER_HOME/system11.1.1.1.32.53.52/DefaultDomain/server/DefaultServer

Every Server Instance requires a unique Application Server Connection. "DefaultServer" Server Instance uses bundled Application Server Connection named "IntegratedWebLogicServer" (see Figure). IntegratedWebLogicServer is used by Integrated WLS for deployment and server management. This connection is visible in the Application Server Navigator and the Resource Palette, and can be used to browse and manage this instance.
With a fresh installation of JDeveloper, the "DefaultServer" Server Instance and the "IntegratedWebLogicServer" Application Server Connection are only created the first time a Integrated WLS related action is taken. The actions are: running/debugging/profiling a Java EE application, editing the Server Instances, or editing the application properties->Run properties. The Server Instance must be started once, after which any application can be run repeatedly. You can also start Integrated WLS without starting application as shown below.

How to Start Integrated WLS

Options for starting Integrated WLS are available in the Run menu in JDeveloper.

To start it in debug mode, from the Run menu, select Debug Server Instance.
It is recommended that the service be run in debug mode as it helps in debugging the service.
To start it in the regular mode, from the Run menu, select Start Server Instance.

There are a couple of ways to determine if Integrated WLS is running:

From the View menu, select Log, and look for the following entry:
```
IntegratedWebLogicServer started
```
Access the Integrated WLS console from a browser using weblogic/weblogic1 credential:
```
http://localhost:7101/console
```

The first time the Integrated WLS starts, it tries to use the first available port in the 7101 - 7105 range. The following message appears as the first line in the Default server log in JDeveloper. You should use the chosen port for all access:

*** Using port 7101 ***
or
HTTP port conflict detected. The HTTP port will be reassigned to port 7102.

When you run your application in JDeveloper using the run or debug commands, the Integrated WLS server starts automatically and your application runs in the target browser. When the Run or Debug action is selected on a Java EE node, Integrated WLS runs the entire application and all its projects as a Java EE Application in a Java EE container ("DefaultServer"). Each node type may optionally trigger additional actions, such as launching a browser.

Adminstration Console

The WebLogic console can be deployed and accessed to manage the Integrated WLS (or "DefaultServer").

To view the DefaultServer details:

Go to your web browser and enter the URL: http://<hostname.domainname>:<port>/console
Login to the WLS console using the username and password: weblogic / weblogic1.
Go to the Domain Structure and select DefaultDomain, Control, DefaultServer(admin).

Launch

When Integrated WSL is started, JDeveloper configure its environment as follows:

D:\Oracle\MIDDLE~1\JDK160~1\bin\java -client
-Xms256m -Xmx512m -XX:CompileThreshold=8000 -XX:PermSize=128m  -XX:MaxPermSize=512m
-Dweblogic.Name=DefaultServer
-Djava.security.policy=D:\Oracle\MIDDLE~1\WLSERV~1.3\server\lib\weblogic.policy
-Djavax.net.ssl.trustStore=D:\Oracle\Middleware\wlserver_10.3\server\lib\DemoTrust.jks
...

For troubleshooting, some of these configuration information can be helpful. For example, it tells you where the domain home directory is; what server instance's name is; where the security policy file is read from, etc. In the following sections, we'll discuss some relevant configuration information and where to find them.

Which Port the Integrated WLS Is Assigned to?

If the port display when the Integratede WLS started was buried deeply in the Default server log in JDeveloper or it's simply scroll out of scope, you can still find out which port number it gets assigned to. Look at <listen-port> element inside config.xml which is located here:

 $JDEV_USER_HOME/system11.1.1.1.32.53.52/DefaultDomain/config

Development Mode or Production Mode

You can check if the server is in development mode or production mode by looking in the config.xml for the domain. If config.xml contains the following xml fragment, then it is in production mode:

<production mode-enabled>true</production-mode-enabled>

For Integrated WLS, its config.xml doesn't contain the above xml fragment. However, you can find if it's in development mode or not by reading the log message in the Log view.

Server Credential Store

There are two ways application credentials can be merged onto the server credential store.

MERGE

MERGE will not change any credential that already exists on the server. For example, if there is a user 'scott' and a password 'tiger' already in the server credential store, and your app wants to change the password for 'scott' to 'foo', it will not work if the mode is MERGE. In order to be able to overwrite a credential on the server, the mode must be OVERWRITE.

OVERWRITE

Overwriting the master credential store with application credentials is a security risk.
The overwrite operation will only work on servers in development mode and also have the overwrite option enabled.

By default, the Integrated WLS is in development mode with OVERWRITE (i.e., -Djps.app.credential.overwrite.allowed=true) flag enabled.

Troubleshooting Web Services on Integrated WLS

Log directory

$JDEV_USER_HOME/system11.1.1.1.32.53.52/DefaultDomain/servers/DefaultServer/logs
Look for DefaultDomain.log, DefaultServer-diagnostic.log, and DefaultServer.log

For more information about logging in Oracle Fusion Middleware, see "Managing Log Files and Diagnostic Data" in Oracle Fusion Middleware Administrator's Guide.
There are two categories of log files that you can reference to assist in diagnosing problems with Web services:

Diagnostic logs--Enable you to access diagnostic data about specific feature components in Oracle Fusion Middleware. For more information, see "Using Diagnostic Logs for Web Services".
There is a set of predefined diagnostic loggers. You can configure your own diagnostic logger, as described in "Configuring a Diagnostic Logger for a Web Service".
Message logs--Enable you to view elements of the SOAP message request. You control message log creation using policies. For more information, see "Using Message Logs for Web Services".

Diagnosing Problems with Oracle WSM Policy Manager

References

Integrated WLS
Running and Deploying Applications on WebLogic Server
How to Test the Web Service Using Integrated WLS
How to Manage the Integrated WLS
How to Start and Stop Integrated WLS
Oracle Fusion Middleware Search Results: integrated WLS

Xml and More

How to Avoid Deadlocks

Volatile Keyword in Java

Singleton Is Not as Simple as You Think

Understanding Garbage Collection

hashCode() and equals() in Java

Object Identity vs. Logical Identity

When to Override equals()

Override hashCode() If equals() Is Overridden

Summary

Read More

IT Job Interview Questions

Questions

Answers

References

Starting the CPU Profiler in JDeveloper

Volume Rendering using MapReduce

Applying MapReduce

Volume Rendering

MapReduce Basics[7,8]

Map and Reduce Tasks

Data Decomposition

InputFormat

Map Function

Sort and Shuffle

Reduce Function

Conclusion

References

Sub-flow Design Pattern

Usage

Overview

Sample Implementation

Implementation Details

Book Review: "Oracle WebCenter 11g PS3 Administration Cookbook"

What's Portal Application?

The Book

Resource Catalog

Trade-offs

ADF View Criteria By Example

Adding WHERE Clause

Creating View Criteria Programmatically

Using Named View Criteria

What's View Criteria

Advantages of Using Named View Criteria

References

Book Review: "Overview of Oracle Enterprise Manager Grid Control 11g R1: Business Service Management"

Business Service Management

Management Issues

The Needs

The Solution

The Book

Resources

Beautifying Table and Column Comments for Design Review

Offline Database

Adding Comments

Generating Comment Table

Conclusion

References

Modeling Data with Offline Database in JDeveloper

What is the Offline Database

Offline Database Model

Metadata SXML Comparison Tool[3]

Working on Data Modeling at Different Levels:

Notes

References

Language Identification

N-Gram-Based Text Categorization

Training Phase

Application Phase

What's in TextCat PR?

Book Review: "Oracle Warehouse Builder 11g R2: Getting Started 2011"

What's Data Warehouse

Data Warehouse vs. Transactional Database

Introduction of the Book

Oracle Warehouse Builder (OWB)

ACME Toys and Gizmos

Summary

See Also

How to Support Property Chain Axiom Using Oracle's OWL Prime

What Oracle Semantic Supports?

MapReduce Basics^[7,8]

Metadata SXML Comparison Tool^[3]

Setting up Global JDBC DataSource

You can create a global data source on Oracle WebLogic Server Administration Console: