[ADF EMG] Essential ADF Design Documents

404 views
Skip to first unread message

akhanof

unread,
Apr 26, 2010, 3:18:20 AM4/26/10
to ADF Enterprise Methodology Group
Dear Muir,

As there are several talks about methodology design regarding ADF I
think that the piece that is missed is the documentation part, I mean
we have to reach an point that result in what is the document that
must be generated and deliver to developer of ADF from designer.
When we are using pure java developing the design document of Class-
diagram or Activity-diagram and other UML diagram would be sufficient
in most of the cases. but in ADF due to its framework it is more
component oriented than Object Oriented so the old design-document can
not be useful and also would put the developers in trouble and
confused.
here I want to propose the design-document which is based on ADF and I
hope that other members make this document more complete and become
the design de-facto for ADF
the steps..
1. the first phase of design beginning from table design, use-case and
any other rudimentary design document that are not specific to ADF
(general design documents which may vary base on each companies design
team)
2. complete the database design to match any specific need for ADF
such as (in most of the cases the below steps would be done in the
step one)
• adding any view needed for any LOV or any other read-only purpose.
• adding any trigger for post insert operation for PK.
3. Documents regarding EO and association between them
4. Detail design the validation on EO and their attributes
5. Documents regarding VO and link between them and also indicating
that each VO is composed of which EO's (in this step we are not focus
on LOV just the main VO's)
6. Detail design the attributes, detecting the attributes that have
specific feature mainly
• Is the attribute Updatable or un-updateable
• Any logic regarding the attributes that must be done in VO
• Detecting lov if any attribute has lov
1. Determining the select that is needed for lov(if it needs any
database-view the view would be add in DB also if it would use any
entity in the step 3 the view for lov would be based on that EO
otherwise just the view based on the query or fixed list of values.
2. Update the view list determined in the step 5
7. Determining the App-modules that are needed local or share and also
the view that each AM must have and the relationships between them,
(maybe it would be a good point to move this step from 7 to 3.)
8. Detail design regarding DML operations
• the needed pseudo-code or logic for the create/remove/update
• write any procedure in DB when the before/after DML operation need a
db-procedure
9. Determining the first look (prototype) of the pages that this
subsystem would have, in the prototype, mainly, the following steps
would be determined
• Views that are used in the page
• Default layout for the page
• Any roles that must be handled such as before going to page.
• Determining the popup
• Any pre-define template that developer must user for this page
10. Determining the flow between pages
11. Determining the bounded-task flows after revising the step 9 the
pages that must be logically be in a unit(bounded-task-flow) would be
determined.
12. Determining the backing-bean that each page must use such as
preserving the state of the user (of course the MB's are potentially
designed with developer and cannot be documented in design phase)
13. determine the security roles and policy for operations, in this
step, the roles regarding each page or operation would be determined
please take in consideration that the goal here is not specifying
every nuance of developing with ADF the goal is firstly avoiding the
repetitive objects in sub-systems if we do not use the above design
principal or any similar documents to determine the objects first(EO/
VO)… that would be a potential for existence of duplicate objects in
sub-systems. Secondly the goal is speeding up the development phase if
the documents are generated then it would be very easy to divide the
task between developer such as 1 developer designing the EO and other
work on UI and so on.
Another point to mention is that this kind of documents can simplify
the maintenance of the system.

All other aspect and procedure would be handled with Programmer in the
developing phase.

Thanks and regards,
Amir



--
You received this message because you are subscribed to the ADF Enterprise Methodology Group (http://groups.google.com/group/adf-methodology). To unsubscribe send email to adf-methodolo...@googlegroups.com

Jan Vervecken

unread,
Apr 26, 2010, 5:38:13 AM4/26/10
to ADF Enterprise Methodology Group
hi Amir

Where you write "... that this kind of documents can simplify the
maintenance of the system ..." I would like to add that they can also
complicate things when those documents are not kept up-to-date with
what has actually been created (developed).

regards
Jan Vervecken

Marcos Ortega

unread,
Apr 26, 2010, 8:56:40 AM4/26/10
to adf-methodology
I'm Facing this exact problem, I'm starting a new project and I want (for the first try) to document using others UML diagrams , always I use just DER; 

See; in front of flow diagram or use case diagram also class diagram , I can't design (visualise) an real world ADF project ;

About a week ago , I was wondering that we could have an special DER, where we could also disign BC4J (appModules) inside, and task-flows also their pages  ( fragment or not );

The main point is that ADF BC4J ( also others framework who have relational arquiteture ) is not totally useful to use classes to represent database tables and theirs relationships;

ADF tasks flows are well represent with taskFlow diagrams, but pages (and fragments) are not represented in this diagrams;

I'm missing a diagram where I can visualize an entire ADF project from top to down;



      Marcos Ortega
 Analista de Sistemas
  Campo Grande - MS
http://www.santoandrea.com.br


2010/4/26 Jan Vervecken <ver...@gmail.com>

Maiko

unread,
Apr 26, 2010, 9:49:02 PM4/26/10
to adf-met...@googlegroups.com, adf-methodology
Diagrams get out of sync with both the spec and code. I haven't been to a single project where diagrams played a key role in the development cycle other than the database model diagram. 

I've successfully used good use case documents plus reasonably document code before, and I don't miss a single bit of any UML diagram, specially when using frameworks.  This is the same way some internal teams at Oracle work and are very successful, specially of they're applying SCRUM in small sprints (1-2 weeks) for the size of their projects.

You'll never be able to see a top down view as you want, and that's actually a good thing; you should be able to piece together individual use cases to assemble your app, and not to start with a virtual model of how the system should be; business is chaotic by it's own nature and by being able to provide a little bit more fine grained functions you'd be able to build composite applications that can better adapt to your needs. 

Well, just my two cents. ^_^  

[]s
Maiko
------------------------------------------
Sent from my iPhone. Please excuse any typos, mistakes, etc.
------------------------------------------

 

Simon Haslam

unread,
Apr 27, 2010, 6:21:53 AM4/27/10
to ADF Enterprise Methodology Group
This is an interesting discussion Amir has started.

I think the documentation approach will depend a little on what type
of application you're building, though let's assume for this case that
it's database-centric with most of the interaction driven through a
web UI.

So in my opinion there are two halves to the design - the data model
and supporting the business processes. Whilst I would accept that the
data model should fall out of the business process design, in practice
I would suggest that the business entities within logical data model
can usually be created relatively easily on their own. This would give
you a first cut physical data model covering all the important
entities such as customer, address, order, order line, or whatever. I
think that doing this early on without considering the UI is a good
thing - the designer and business users should be able to agree on
most of it. This then gives us the first cut database design and a set
of BC Entity Objects. I realise that this is rather "old school" but
having a close correspondence between the business and the data model
plays to the strengths of both the relational database and the ADF BC
mapping. (If I go to a site where I see a table named something like
"OBJECTS" it always rings alarm bells since it makes life very
difficult for the database).

Then we need an approach for the second half - modelling the business
processes and use-cases. Task flows give us a good opportunity to
model the business process (this is why they are such a great feature
of ADF Faces RC) but as Maiko says there doesn't seem to be a good way
to model the interface. This is especially true with these modern
desktop-style UIs (like the UI shell) where functionality is
encapsulated in fragments of a page (and so could be used in different
contexts) rather than the page as a whole. So I don't really have any
great ideas in this area as yet...

Marcos: excuse my ignorance but what's a DER diagram? Could you post a
link?

Finally the UI will then dictate the View Objects (and Application
Modules) required, and probably additional attributes in the
underlying data model. Therefore invariably there are iterations to
incorporate those into the data model and entity objects.

I agree with Maiko that diagrams very quickly get out of date - having
seen all sorts of tools (from the CASE ones in the late 80's onwards)
they all suffer if there's not a direct and automatic relationship
between the diagram and the code. Therefore if we could use the ones
in ADF (BC, task flows) that would be preferable (I wonder if there is
a way to automatically build them into a document, e.g. with ant?).

I think my main concern is getting a method that maximises re-use.
With a project larger than 3 or 4 developers it could be very easy for
people to recreate duplicate, subtly different, chunks of UI
functionality, and some sort of method to design things up-front would
cut down on wasted effort.

:Simon

Marcos Ortega

unread,
Apr 27, 2010, 11:36:01 AM4/27/10
to adf-methodology
Sorry Simon

   DER is in portuguese  :(      my mistake !!

  Data Base Diagram, i was intended to say;


   The main point is ....

          I did not use any UML diagram , until now, because I do not know how to imagine an ADF application ;  


    Maiko Says;


You'll never be able to see a top down view as you want, and that's actually a good thing; you should be able to piece together individual use cases to assemble your app, and not to start with a virtual model of how the system should be; business is chaotic by it's own nature and by being able to provide a little bit more fine grained functions you'd be able to build composite applications that can better adapt to your needs. 


   well done words;

   So , let me know , one application will have so many diagrams , that they must be very well organized; don't they ?

   how do we diferentiate , steps located in database ( pl/Sql Code ) and routines in java ( or ADF faces events an so one );

   Or does it do not metter at all ??

Thanks !


        

   


      Marcos Ortega
 Analista de Sistemas
  Campo Grande - MS
http://www.santoandrea.com.br


2010/4/27 Simon Haslam <Sim...@veriton.co.uk>

Maiko Rocha

unread,
Apr 27, 2010, 7:53:27 PM4/27/10
to adf-met...@googlegroups.com
I could reply it in ptBR but I will keep english as the official language. ;-)


   So , let me know , one application will have so many diagrams , that they must be very well organized; don't they ?

   how do we diferentiate , steps located in database ( pl/Sql Code ) and routines in java ( or ADF faces events an so one );

   Or does it do not metter at all ??

Bottom line is that it really doesn't matter - well, at least for me ;-). Most of the times the Use Case is the "integration" document, so for example when implementing UC1 its documentation could have a reference to the PL/SQL packages to be used; even better, you can extract the PL/SQL routines straight from the database, use something like pldoc, or document that yourself manually - and cross-reference it with the UC documentation. In this case the WIKI format would be the best way to do this. 

One thing that we're doing internally for Fusion Apps is to harvest the source control repository and by cross-referencing workspaces, projects and ADF Libraries we can build a (humongous) dependency graph that is used to find invalid  and non-compliant references and above all to optimize the build process. This is not something that you'll ever going to need or even take advantage off if you are not managing 2000+ developers worldwide writing 11.000K task flows, for example. :-)

Even for the database what I'd do is just have a reference to the table names involved in the UC and create my on DB diagram by reverse engineering it from the database so I could understand the relationships. No more wall-sized printed diagrams at the IT office! =-)

[]s!
Maiko

Steve McK

unread,
Apr 28, 2010, 4:05:43 AM4/28/10
to ADF Enterprise Methodology Group
I also find this an interesting topic. My perspective is organising
the roles on the development project, where they can add value during
the Systems Development Life Cycle (SDLC) and the interaction with ADF
when this is the preferred approach. The SDLC roles I'm interested in
are Business Analyst, Designer (perhaps Architect) and Developer. So
on a medium sized project where are the roles involved and what is the
optimum 'documentation' produced by each role to communicate and
expand the solution with the next role to ensure the customer gets
what is required and IT gets a maintainable solution.

Is there any advantage in the Business Analyst documenting the
business requirement using the UML in JDeveloper ADF?
Yes - it will help with communication between roles. It will also
provide some measure of requirements tracking.
Yes - all project documentation is together and it can be version
controlled. But,
No - if it's not linked with the code and maintained with the code
then it's only a means to an end and can be produced in any diagram
tool.

I would support Simon's contention that a Logical Data Model for the
solution domain showing the main business entities is useful.
Producing a first database design from this is a useful
'documentation' to allow the designer and developer to communicate. It
may be 'old school' but throwing the baby out with the bath water
isn't wise.

I think what Amir sets out to do is worthwhile accepting that one size
doesn't fit all. I need to spend a bit more time working through his
stages and steps. I would like to be clearer about how to plan the
approach for our first project using ADF & JDeveloper 11g.

Maiko - what SDLC roles are involved in your Fusion Apps development?



On Apr 28, 12:53 am, Maiko Rocha <maiko.ro...@gmail.com> wrote:
> I could reply it in ptBR but I will keep english as the official language.
> ;-)
>
> *   So , let me know , one application will have so many diagrams , that
>
> > they must be very well organized; don't they ?*
>
> *
>
> > *
>
> *   how do we diferentiate , steps located in database ( pl/Sql Code ) and
>
> > routines in java ( or ADF faces events an so one );*
>
> *
>
> > *
>
> *   Or does it do not metter at all ??*
>
> Bottom line is that it really doesn't matter - well, at least for me ;-).
> Most of the times the Use Case is the "integration" document, so for example
> when implementing UC1 its documentation could have a reference to the PL/SQL
> packages to be used; even better, you can extract the PL/SQL routines
> straight from the database, use something like
> pldoc<http://pldoc.sourceforge.net/>,
> or document that yourself manually - and cross-reference it with the UC
> documentation. In this case the WIKI format would be the best way to do
> this.
>
> One thing that we're doing internally for Fusion Apps is to harvest the
> source control repository and by cross-referencing workspaces, projects and
> ADF Libraries we can build a (humongous) dependency graph that is used to
> find invalid  and non-compliant references and above all to optimize the
> build process. This is not something that you'll ever going to need or even
> take advantage off if you are not managing 2000+ developers worldwide
> writing 11.000K task flows, for example. :-)
>
> Even for the database what I'd do is just have a reference to the table
> names involved in the UC and create my on DB diagram by reverse engineering
> it from the database so I could understand the relationships. No more
> wall-sized printed diagrams at the IT office! =-)
>
> []s!
> Maiko
>
> On Tue, Apr 27, 2010 at 8:36 AM, Marcos Ortega <mar...@santoandrea.com.br>wrote:
>
>
>
>
>
> > Sorry Simon
>
> >    DER is in portuguese  :(      my mistake !!
>
> >   Data Base Diagram, i was intended to say;
>
> >    The main point is ....
>
> >           I did not use any UML diagram , until now, because I do not know
> > how to imagine an ADF application ;
>
> >     Maiko Says;
>
> > *You'll never be able to see a top down view as you want, and that's
> > actually a good thing; you should be able to piece together individual use
> > cases to assemble your app, and not to start with a virtual model of how the
> > system should be; business is chaotic by it's own nature and by being able
> > to provide a little bit more fine grained functions you'd be able to build
> > composite applications that can better adapt to your needs. *
> >> unsubscribe send email to adf-methodolo...@googlegroups.com<adf-methodology%2Bunsubscribe@­googlegroups.com>
>
> >  --
> > You received this message because you are subscribed to the ADF Enterprise
> > Methodology Group (http://groups.google.com/group/adf-methodology). To
> > unsubscribe send email to adf-methodolo...@googlegroups.com<adf-methodology%2Bunsubscribe@­googlegroups.com>
>
> --
> You received this message because you are subscribed to the ADF Enterprise Methodology Group (http://groups.google.com/group/adf-methodology). To unsubscribe send email to adf-methodolo...@googlegroups.com- Hide quoted text -
>
> - Show quoted text -

susan duncan

unread,
Apr 28, 2010, 6:51:20 AM4/28/10
to adf-met...@googlegroups.com
I'm, of course, interested in the comments on using a UML model and creating first cut datamodel from this. Have you tried doing this in JDeveloper? I've written a tutorial about using the UML class modeler and then transforming that to a Physical DB model and would be intrested in your comments on how this works for you

http://www.oracle.com/technology/obe/obe11jdev/ps1/databasedevelopment/obe_%20databasedevmt.htm

rgds

Susan

Simon Haslam

unread,
Apr 28, 2010, 7:37:35 AM4/28/10
to ADF Enterprise Methodology Group
As a slight aside: whilst inevitably a documentation question like
this turns into a process one (since I think it's fair to say a
standard ADF development process isn't very well defined yet) can I
point readers to a discussion about methodology last month for
interest:
http://groups.google.com/group/adf-methodology/browse_thread/thread/b9660be86a823f25

In particular see the detailed post from Liza Lyons on Mar 25 about
how Oracle has been tackling this for Fusion Apps.
(I am conscious it's easy for old discussions to "drop off the radar"
- maybe this is one we should try to summarise on an EMG or wiki page)
Reply all
Reply to author
Forward
0 new messages