Jason Bennett's Developer Corner

(Originally posted on the “old” Jason Bennett’s Developer Corner, Sunday, August 17, 2008)

I recently had the challenge of creating several complex query search screens using ADF Faces.  These new search screens had to integrate seamlessly into our current application’s (not a J2EE application …) search screens (look the same, act the same, feel the same …).  One of the challenges that presented itself was to determine how to pass multiple search parameters with various operators (=, <, LIKE,SOUNDEX, etc …) and the values associated with them and map them to their associated columns in a dynamic where clause.  Since I was creating multiple screens with similar functionality, I needed a generic method of parameter passing.  The obvious answer was to use some sort of array or combination of arrays as the parameter transport mechanism.  The not so obvious part was how the heck I was going to pass an array of Java Objects to a PL/SQL function that was expecting a PL/SQL Collection object.  Luckily, this turned out to be less complicated than I thought thanks to Oracle and the developers of JDBC.  The Java to PL/SQL user-defined type mapping is accomplished using the java.sql.SQLData interface (http://java.sun.com/j2se/1.5.0/docs/api/java/sql/SQLData.html).  This interface was designed to allow for the mapping between a SQL UDT (user defined type) and a Java class.  The mapping of an array of these objects to an Oracle collection (or array) is accomplished using two Oracle JDBC classes: oracle.sql.ARRAY (http://www.oracle.com/technology/docs/tech/java/sqlj_jdbc/doc_library/javadoc/oracle.sql.ARRAY.html) and oracle.sql.ArrayDescriptor (http://www.oracle.com/technology/docs/tech/java/sqlj_jdbc/doc_library/javadoc/oracle.sql.ArrayDescriptor.html). Next problem … how to create a custom (generic) Programmatic ViewObjectImpl class that will accept a Collection object  as the parameter passing mechanism.  This turned out to be another simple task with the help of some Oracle ADF documentation: (http://download.oracle.com/docs/cd/B31017_01/web.1013/b25947/bcadvvo008.htm).  After that, it’s elementary!  All of the View Objects defined for each of my custom search screens were extended from this new custom ViewObjectImpl class.  The rest of this article details the steps and code I used to implement the solution.  For the sake of brevity, I will limit the code to just the generic ViewObjectImpl and PL/SQL collection mapping.  (The PL/SQL package used to implement the searches has some interesting bits of code, and I will publish that in a separate article.)

Step 1. Create SQL User Defined Types

Step one is to create the SQL user defined types.  In this instance I created two types.  The base type SEARCH_PARAM_TYPE and a collection of SEARCH_PARAM_TYPE called SEARCH_PARAM_ARRAY.  These two user defined types are defined by the following commands:

CREATE OR REPLACE TYPE SEARCH_PARAM_TYPE AS OBJECT(

PARAM_NAME      VARCHAR2(100),

PARAM_OPERATOR  VARCHAR2(4),

PARAM_VALUE     VARCHAR2(1000)

)

/

CREATE OR REPLACE TYPE SEARCH_PARAM_ARRAY AS TABLE OF SEARCH_PARAM_TYPE

/

The SEARCH_PARAM_TYPE contains a parameter name (or label or identifier), a parameter query operator code, and the value for the particular parameter.  The SEARCH_PARAM_ARRAY is just a simple array (PL/SQL Table) that may hold 0 or more SEARCH_PARAM_TYPES.  Each of these SQL types gets mapped in the Java code.

Step 2. Create Java Class to Match SQL Type SEARCH_PARAM_TYPE

Step two is to create a Java class to match the SQL user defined type SEARCH_PARAM_TYPE.  This class must implement java.sql.SQLData and java.io.Serializable.  The code below demonstrates how to implement the class that matches the SQL type SEARCH_PARAM_TYPE:

As you can see, this is a pretty straight forward class.  It is important to note that in the writeSQL method above, the order attribute assignements defined with the stream.writeString statements must match the order of attributes as defined in the SQL user defined type exactly (under the covers I’m sure it has to do with marshalling and unmarshalling the serialized objects and not knowing how to intuitively identify what value goes where).

Step 3. Create the Custom ViewObjectImpl Class

The third step is to create the (generic) custom ViewObjectImpl class that your actual ViewObjects will extend.  As stated at the start of this article, I made use of the example in the Oracle ADF documentation that details how to create a View Object using alternate data sources.  The key piece of code is the callStoredFunction method:

The custom ViewObjectImpl also has methods that construct the ArrayList containing SearchParamBeans.  There are getter and setter methods provided in the class for adding and retrieving SearchParamBean objects. The SearchParamBean[] array you see in the code above is generated internally by the method:

/**
* Constructs the SearchParamBean array from the searchParams ArrayList
* @return
*/

protected SearchParamBean[] getParamBeanArray(){

return (SearchParamBean[])searchParams.toArray(new SearchParamBean[searchParams.size()]);

}

Rather than explain each method in detail, I’ll provide the code with appropriate comments.  It’s fairly straight forward code:

Step 4. Create a View Object based on the Custom ViewObjectImpl

The last step is to create a new ViewObject based on the custom ViewObjectImpl that was created in step three.  The easiest way to do this is to use the JDeveloper View Object creation wizard.  Select the ”Rows populated programmatically”  option.  Add any attributes (return columns) you need.   Under the Java section of the View Object definition, and set the VO to extend the new ViewObjectImpl class.   Edit the new View Object class and configure it to use the correct PL/SQL (packaged) functions.  Here is an example:

Wrapping it Up …

This article illustrated how to create a custom ViewObjectImpl class that passes an array of Java objects to a PL/SQL Collection based upon a user defined type.  The article touched on a lot of peripheral topics: Creating custom ViewObjectImpl’s, mapping Java objects to SQL user defined types, and converting a Java Object Array into an Oracle Collection/Array.  Basically, it covered a lot of ground in a very brief text.  If you have questions (or suggestions) please feel to shoot me an email.

(Originally posted on the “old” Jason Bennett’s Developer Corner, Thursday, June 05, 2008)

In this entry, I’ll go over my technique for using a single JSP for both inserting and updating data. This technique utilizes custom methods in the target ViewObjectImpl class, and Page Definition action methods in the Page Definition associated with our ADF/JSF JSP. There are probably other ways to do this, but this one is fairly straight forward. (Note: I believe Steve Muench recommended a similar technique using methods in the ApplicationModuleImpl class)

Preparing the View Object

Most of the View Objects in my applications (that are used for data entry) contain a bind variable in the WHERE clause that is associated with the target table’s primary key (I use dumb keys versus natural keys).   In order to put the page in update mode, we need to pass a PK value to the View Object and pre-populate it prior to rendering the page.  Otherwise, the page is rendered in insert mode.  This is pretty much a universal concept.  How do we go about passing the PK value (or parameter) to the View Object?  First, we need to create a couple of custom public methods in the View Object’s ViewObjectImpl class.   One method will take the PK param value and pre-populate the View Object instance, and the other method will clear the state of (empty the data from) the current instance of the View Object.   The  methods look  like this:

Preparing the Page Definition File

ADF Faces JSPs use an XML based Page Definition file to bind data to the user interface and to perform some actions prior to rendering the page (overly simplified definition …).  Each View Object referenced by an ADF Faces JSP component is represented in that page’s Page Definition file.  ADF Faces comes with some canned page actions (such as Create and Delete) that can be “dropped” into the page definition file and then applied to event (or actions) that occur later in JSP page.  We can also create custom actions (known as method actions) that are mapped to methods we have created.  The two methods we created in the last section (queryViewById and clearView) will be included as custom method actions the Page Definition file for our ADF/JSF JSP page.  The method action entries go in the “bindings” section of the page, and look like this (I have my own View Object referenced in the example):

<methodAction
MethodName=”clearView”
RequiresUpdateModel=”true” Action=”999″
IsViewObjectMethod=”true” DataControl=”AppModuleDataControl”
InstanceName=”AppModuleDataControl.MyemployeeView1″/>

<methodAction
MethodName=”queryViewById” RequiresUpdateModel=”true”
Action=”999″ IsViewObjectMethod=”true”
DataControl=”AppModuleDataControl”
InstanceName=”AppModuleDataControl.MyemployeeView1″>
<NamedData NDName=”p_id” NDValue=”#{param.p_emp_id}”
NDType=”java.lang.String” />
</methodAction>

Notice the “#{param.p_emp_id}” in NDValue attribute above.  Any request parameter passed to the your page can be accessed using “#{param.<parameter name>}”.  The only caveat is if you use the <f:param> tag in conjunction with a command link or command button and the navigation rule behind your navigation action specifies a “redirect” … the parameters will not be passed.  Here is a quick break down of the attributes for the “methodAction” tag above:

• The “id” attribute represents the identifier of this methodAction tag as it relates to other components (tags) in the current Page Definition file.
• The “MethodName” attribute defines the binding name for this method action when called from the “invokeAction” tag ( tag that is responsible for executing the code).
• The “RequiresUpdateModel” attribute specifies whether or not the model needs to be updated prior to executing the method.
• The “Action” attribute identifies the internal class for which the data control is created.  Always seems to be 999 for custom class.
• The “IsViewObjectMethod” attribute indicates whether the method being invoked is defined within a View Object.
• The “InstanceName” attribute points to the View Object instance as defined by the application data control.
• The “NamedData” tag is used to map any parameters that the method might take. It contains attributes “NDName” (method parameter name), “NDValue” (value being passed), and “NDType” (data type of the parameter).

In order for the page to be rendered in INPUT mode, we have to include a “Create” action in the page definition.  Place the following tag in the “bindings” section (before or after the “methodAction” tags):

<action IterBinding=”MyemployeeView1Iterator”
InstanceName=”AppModuleDataControl.MyemployeeView1″
DataControl=”AppModuleDataControl” RequiresUpdateModel=”true”
Action=”41″/>

(Note:  The instance name references my View Object … you would replace the reference with yours.)

The next step in preparing the Page Definition is to add “invokeAction” tags to the “executables” section.  The “invokeAction” tags define what actions will be executed and under what conditions they will be executed.  The invoke actions for our methods look like:
<invokeAction
Binds=”clearView”
RefreshCondition=”#{adfFacesContext.postback == false and not empty param.p_emp_id}”
Refresh=”prepareModel”/>

<invokeAction
Binds=”queryViewById”
RefreshCondition=”#{adfFacesContext.postback == false and not empty param.p_emp_id}”
Refresh=”prepareModel”/>

<invokeAction Binds=”Create”
Refresh=”renderModel”
RefreshCondition=”${adfFacesContext.postback == false and empty param.p_emp_id and empty bindings.exceptionsList}”/>

The “RefreshCondition” condition attribute determines whether or not the action will be triggered. The three action invocations below determine how the page will be rendered to the user. If  the call to the page is not a post back from the current page, and the “p_emp_id” param is not null, then associated View Object(s) will be cleared of existing data, passed the p_emp_id param and will execute and populate. This will put the screen in UPDATE mode.  Otherwise, if the “p_emp_id” param is null and the call to the page is not a post back, the screen will be presented in INSERT mode.

Passing a Parameter to the Page

Passing a parameter is a fairly simple matter.  You could pass it via a command link or command button with a param tag (NOTE: The navigation rule definition for the “action” can not contain a redirect reference.):

<af:commandButton text=”Some Text” action=”SomeAction”>
<f:param value=”123″/>
</af:commandButton>

or

<af:commandLink text=”Some Text” immediate=”true”
action=”SomeAction”>
<f:param value=”#{somebinding.value}”/>
</af:commandLink>
You can also pass a parameter via a standard URL:

http://someserver.some.domain:7778/myapp/faces/somepage.jsp?p_emp_id=123

Passing no parameters will result in the page rendering in INPUT mode.

Wrapping It Up …

As always, if you have questions, or input, please shoot me an email.

(Originally posted on the “old” Jason Bennett’s Developer Corner, Saturday, March 15, 2008)

You may have noticed that ADF Faces generates some very specific JavaScript code for handling page level (tag level) events (onclick, onChange, onBlur, etc …). These event handlers “handle” all of those cool features such as “Partial Submit” and “Auto Submit”. Most of the time, we as developers (and users of ADF) have no direct control over where these framework generated event handlers are placed, or specific control over when they will fire. The focus of this entry is on how to move a generated event handler from one event to another on the same tag. For example: Let’s say that you want to implement a feature that will allow a user to type in an employee Id and then have the rest of the employee information (name, etc ..) auto populate. No problem, you just bind a method from a backing bean to a ValueChangeListener and turn on Auto Submit and you are done! However, what if you also want to use a command link to implement an LOV dialog on the same data entry field and use the data (i.e. the employee id) to limit the results of the LOV? Now you have a problem. If you enter data in the employee id field, and then try to navigate to your LOV link, the value change event (onChange) fires before the LOV triggers and nullifies the LOV event. The solution to the problem is obvious … just change the triggering event from onChange to onKeyPress (for the auto population … you would also need to add code to check for the triggering “Hot Key”). But wait … that code was generated by ADF Faces. We (the developers) have no direct control over where they place their code. Now, the problem becomes slightly more challenging (or interesting). The solution (one solution anyway …) is to write a JavaScript function that will move it for you and leave the original code intact. My version of the function looks like this:

The function, moveEventFunction, will move or swap the code assigned to one event handler and move it to a new event handler on the same node (or tag). The function also gives the developer the option of wrapping a new conditional (Boolean) function around the original event handler code.

Now that we have a solution, how do we apply it? You have a couple of options. First, place the call to moveEventFunction at the bottom of the page (between script tags). It will fire after all of the ADF/JSF HTML has been rendered.

<script>

moveEventFunction(<id of target tag>,<existing event name>,<new event    name>,<optional conditional function>);

</script>

However, if you plan on making the target tag a partial target (dynamic refresh), you will lose the swap. The second option handles this situation. Place the call on the onFocus event of the target tag. Doing so guarantees it the swap:

onFocus=”moveEventFunction(this.id,<existing event name>,<new event name>,<optional conditional function>);”

The conditional function (the last parameter) can perform multiple tasks prior to executing the main function (original function). In the case of the scenario above, the conditional function would check for the “Hot Key” that triggers our auto population. However, it must return true or false at the end of its execution.  The conditional function needs to be defined in the manner:

var fnc_MyConditionalFunction = function MyConditionalFunction(){ …}

This will allows allows you to pass the actual function as a parameter without it actually being executed (or evaluated) . Instead of passing in MyConditionalFunction, you pass in fnc_MyConditionalFunction.

(Another option that isn’t JavaScript related might be to get an instance of the UIComponent prior to page rendering and make the swap … haven’t tried that yet.)

(Originally posted on the “old” Jason Bennett’s Developer Corner, Thursday, March 06, 2008)

If you decide to execute a SQL statement or some PL/SQL code from with your ADF Faces application outside of the ADF BC framework (i.e. without using Entity Objects and View Object), you will need access to a JDBC connection.  Do you need to instantiate your own connections, or maintain a separate connection pool?  The answer is no!  ADF BC provides us with (abstracted) access to the JDBC connection object that is associated with our current application session.  Access is provided through the oracle.jbo.server.DBTransaction class.  You can get an instance of the DBTransaction object from several places within the ADF BC Framework: ViewObjectImpl, TransactionEventImpl, EntityImpl, and ApplicationModuleImpl.  All of these classes have a method called getDBTransaction() that return an instance of the DBTransaction object.  Armed with this knowledge, how do we go about getting an instance of DBTransaction anytime we want one?  By “anytime time we want one”, I mean externally from a View Object or Entity Object instance.  The answer is pretty simple.  We just need to access to an instance of the current ApplicationModule.  Using the following code, you can get a DBTransaction object anytime you want:

Place the code listed above in a utility class. I prefer to use a static class or Singleton.

(Originally posted on the “old” Jason Bennett’s Developer Corner, Thursday, January 31, 2008)

This entry covers how to retrieve values from a SelectOneChoice component that is backed (populated) by a ViewObject as defined in a ADF Faces page definition file.

I’ve been working on a fairly large and complex ADF Faces project for my current employer.  I often find myself having to both retrieve and set values in SelectOneChoice components in my backing beans.  I was initially confounded by the fact that the HTML generated by the component did not include my own code values behind the select options. Rather, each option (option tag) uses a numeric value instead of the actual code you would normally see if you were creating the HTML yourself (such as “NC” as the code for description “North Carolina”).  After some digging, I found that the numbers correspond to the Iterator index values of the Iterator that is bound to SelectOneChoice component.   By the way, setting the valuePassThru attribute on the component to true did not work for some reason.

Armed with this new knowledge, I was able to create two utility methods that reside in my base (utility) managed bean class.

The first method, getSelectOneChoiceValues, retrieves both the code (the actual code from your database or view object) and the description value from the Iterator that is bound to the SelectOneChoice component given the index value.  Here is the code for first method:

(Originally posted on the “old” Jason Bennett’s Developer Corner, Friday, November 23, 2007)

Over the last few months, I’ve been working on an ADF based project for my current employer.  The project is my first venture into JSF and ADF.  In this time I’ve developed a little base class that I extend when creating a backing bean (or managed bean) for my pages.  The base class contains several helpful utility methods that I thought I would share.  Some of these I discovered for myself, and a few others were inspired by samples provided by folks like: Steve Muench, Frank Nimphius, and Jonas Jacobi.  I have put the code below.  Each method has a comment at the top to explain what the method does:

The Code …

(Originally posted on the “old” Jason Bennett’s Developer Corner, Monday, July 23, 2007)

If this one is common knowledge, then forgive me.  I just jumped into ADF and JSF a few weeks ago (I was a STRUTS man), and am drinking from the firehose!  There is a property on some of the ADF Faces components (inputText, selectOneChoice, etc …) called “required”.  If set to true, this property will ensure that the user enters a value for the item (in DB terms, it makes the field a NOT NULL field).  This is a convenient feature with one small exception.  Setting the property to true places a green asterisk(*) on the left side of the data entry item.  The asterisk appears whether you want it to or not  and there is no option/property available for turning it off (NOTE: This is an ADF inputText feature, not a standard JSF inputText feature).  This is an issue if your development standards say to put an asterisk on the RIGHT side of the input field (as mine do).

The solution to the problem was fairly straight forward.  Since I had implemented a custom skin for this ADF Faces application and created a custom CSS document (see this article by Jonas Jacobi), I simply over-rode the existing style for the required icon with this one:

.AFRequiredIconStyle { display:none }

Presto!  No more little green asterisk.