Learn techniques for decomposing system requirements into a living, breathing Oracle ADF application.
Chapter 1 - Where's My Parcel?
Poor Betty is in tears. Yet another customer has rung up and shouted at her demanding to know where their overnight package is. Our bos, knows full well that ACME Parcels is prone to losing shipments, and our poor call center—namely, Betty—is looking for a solution.
Perhaps foolishly, while listening to the boss describe the problem for the nth time, you suggest that it wouldn't be too hard to build a Web application in Oracle JDeveloper 11g's Oracle Application Development Framework (ADF) to allow customers to retrieve the status of their parcel from the company's underlying Oracle database.
Quick as a flash, our boss agrees and wants us to sit down with him to sort out the details.
Most programmers like diving into coding to solve any problem. Yet we've learnt our lesson in previous project disasters that a great technique for designing web pages is storyboarding.
Storyboarding is a technique used by the film industry to draw out all the scenes of a movie before live shooting. This includes everything from how the camera pans to lighting angles and where the actor should move. All for dramatic effect, but much cheaper than filming the real thing.
Storyboarding is an ideal technique to use for Web page design, too. Simply sit down with your users and a whiteboard, and through an open dialog, get them to describe their system on the whiteboard, literally showing the screens they want, the fields, the interactions, and so on. In the margins we make as many annotations as we can to describe what the screen(s) will do.
After chatting with our boss in front of a whiteboard of scribbled notes we've come up with the following solution:
We're excited because the storyboard conveys a lot of the information that we need to build our application, without the need for an incredibly dull requirements-gathering exercise and dreary requirements specification.
The storyboard also reveals some interesting facts about our system:
* The results area can show more than one result thanks to duplicate data in our database table. This isn't ideal but we'll work with it, by hiding the results data for privacy concerns if more than one record is returned.
* The recipient's names are stored in uppercase in the database, but we don't want to be that restrictive on the search so we'll convert the string data for the user. Somewhat more problematically, thanks to an old waybill number formatting standard, sometimes customers include hyphens in their waybill number using the old standard. We'll need to remove those before the query.
Requirements are tricky things. From experience, we know that our boss is one who likes to throw in requirements even if they aren't truly required, but just "nice-to-haves". As seasoned programmers, we know that some requirements aren't truly onerous to implement, but others take weeks, and you don't discover this until you start implementing them.
This time we've decided to sit down with the boss and prioritize the requirements. We've found the MoSCoW prioritization technique that sorts requirements into four categories:
1. M—MUST have this
2. S—SHOULD have this if at all possible
3. C—COULD have this if it does not affect anything else
4. W—WON'T have this time but WOULD LIKE in the future
1. MUST have this
Initially we only need the search fields and result. Our boss realizes that because we're still likely to continue receiving phone calls about parcel delivery, we can provide this facility to the ACME Parcels call center staff and they don't need to accept the terms and conditions nor identify themselves as the package recipient or sender.
In turn our staff will be trained to enter the search fields in the correct format (uppercase, and the waybill number without hyphens) so it's not necessary to convert the data to uppercase nor fix the waybill numbers at this stage. However it is important to ensure that all the search fields are entered before the query is executed.
Finally if the results show more than one record, there are no privacy concerns in showing our staff multiple results.
2. SHOULD have this if at all possible
If and when we deliver the search facility to the internet, we agree that it's essential to enforce that the user accepts privacy terms and conditions before undertaking the search. Last time a customer complained that it was possible to look up her details on our systems from the internet. So this time we'll protect ourselves by including terms and conditions that force the user to accept or reject the fact that they represent the parties who sent or are receiving the parcel.
Therefore it becomes essential to store the user's accept/reject choice in an audit table in the database, as well as the user's IP address so we can track who used the facility.
Because privacy becomes an issue if we deliver the system to the internet, it's essential that if the search facility returns more than one record, no results are shown, and the customer is asked to call us instead.
For the internet it's also essential that we convert string data to uppercase and remove the waybill hyphen if supplied.
3. COULD have this if it does not affect anything else
Once the solution is on the Web, it'd be great if we could track adoption of the system and how successful our customers are in finding results. If we have time we'll build in the facility to audit the search criteria and store them in the database, as well as the number of records returned. This will enable us later to see how many queries have been undertaken, what search parameters were entered, and if the query failed, and therefore whether there is anything we could change to make the system easier to use.
4. WON'T have this time but WOULD LIKE in the future
In parting our boss wonders about malicious access: what to do about somebody using the facility to search for results they shouldn't see. We agree that we could build in a facility to block any IP address that has undertaken three queries in the last hour but failed to find any results. At this time however because we're not expecting any malicious access this feature will be left untill a later implementation.
At the conclusion of our requirements-gathering, one problem with greenfield development is knowing where to start. When you have an array of requirements in front of you, it's hard to know what to focus on first. What we really want is a divide and conquer approach, to break the overall problem set into discrete solvable units. With our newly adopted storyboarding and MoSCoW techniques as described above, we can see that the requirements fall into a nice set of categories that we can focus on one at a time.
Once we start to consider our first MUST-have requirement—namely, the ability to search for the status of a parcel—we can then further divide the solution into solvable parcels (no pun intended) in the Oracle ADF framework with Oracle JDeveloper 11g.
We know that in using Oracle ADF we have Oracle ADF Business Components to retrieve the data from the database and Oracle ADF Faces RC to display the data in a Web page. Because we need to search the data and get the data first, we should focus on our Oracle ADF Business Components solution first.
We know in Oracle ADF Business Components that we create View Objects to fetch data from the database, and Entity Objects to write data back to the database. In this first phase of the application we're never interested in writing data back to the database (just querying) so the View Object is the only construct we're interested in.
On considering the ADF BC View Object we know it executes a SQL query against the database to fetch data. But data from what? What's the table we're working with here?
In our fictitious ACME Parcels the Oracle database contains the following table:
CREATE TABLE parcels (
lodged_with VARCHAR2(4) NOT NULL
,rec_first_name VARCHAR2(100) NOT NULL
,rec_last_name VARCHAR2(100) NOT NULL
,waybill_number VARCHAR2(10) NOT NULL
,sender VARCHAR2(100) NOT NULL
,location VARCHAR2(100) NOT NULL
,status VARCHAR2(9) NOT NULL
,last_update DATE NOT NULL
FOREIGN KEY (lodged_with) REFERENCES orgs(id));
We're not overly happy with the table structure; it doesn't have a primary key or a unique key and it includes duplicate records thanks to one of our subsidiaries re-using waybill numbers. But we'll live with it for our design. Here's a sample of the records in it:
Chapter 2 - "Must-Have" Requirements: A Basic Search Application
In this section you'll learn how to build the must-have requirements; initially you only need the search fields and a basic search screen.
Chapter 3 - "Should-Have" Requirements: Creating an App for the General Public
Learn how to build should-have requirements such as logging of the user's IP address if they accept our terms and conditions and enhanced search capabilities.
Chapter 4 - "Could-Have" Requirements: Logging Search Criteria
Learn how to log all search criteria entered by the user, as well as the number of records returned. This will enable you to monitor how useful the search page is.
Chapter 5 - "Won't-Have" Requirements (But We'll Implement Them Anyway): Preventing Malicious Access
Shows how you can add some functionality to prevent malicious access by blocking any IP address that has issued three queries in the last hour but failed to find any results.