ADF Coding Standards

Introduction
This document sets out standards to cover the naming and project structure for ADF
applications as discussed amongst ADF practitioners. The motivation for this piece of work is
to give development teams, particularl those new to ADF, conventions which assist them to
develop applications to !est practice, as well as making the code more familiar to developers
who are new to a project.
Contri!utors
The discussions that have led to this document were started ! Simon "aslam and Chris #uir
on the ADF #ethodolog $oogle $roup. It includes man contri!utions from Aino
Andriessen, %ohn Flack, %ohn Stegeman, &dwin 'iemond, Andrejus 'aranovskis, (eon,
#arko #itic, Avrom )o*Faderman, +athalie )oman and )o! +ocera ,who kindl presented
a summar of this work at an -nconference session of .racle .pen/orld 01123.
"ow 4ou Can 5articipate
This document is ver much 6work in progress6 and some aspects of it ma !e more
controversial than others. If ou would like to contri!ute improvements, or if ou disagree
with an points mentioned, please start a discussion on the ADF #ethodolog group first
!efore editing this wiki page. This is so that the document itself remains consistent and
!roadl in agreement with the consensus of the ADF communit.
Technologies in Scope
These standards cover applications !uilt using ADF Faces and ADF 'usiness Components
and are intended for ADF 77g onwards * some ma !e suita!le for earlier versions !ut that is
down to the reader8s interpretation. The standards are designed to appl to moderate*si9ed
enterprise applications ,sa 711 -I pages for e:ample3 !ut hopefull with some su!division
of packages would !e suita!le for far larger applications too. Smaller applications ,sa 71*01
pages3 ma find this overkill, although it is alwas worth !earing in mind that a successful
small project can often evolve into a much larger one; The focus at this stage is for -I*driven
applications, rather than ones providing predominantl we! service interfaces, though this
ma change over time.
/h "ave Coding Standards<
Standards help promote a uniform =look and feel8 to code, it makes the code easier to
maintain as it !ecomes more intuitive where to find things. ' giving developers guidance as
to how to name items, coding standards save time and effort. Finall ! setting out the wa
code is organised standards can improve application structure and foster !est practices.
Currentl this document is restricted in scope to cover the naming conventions for ADF items
and packages ,and ! implication logical structure3> other more detailed, sa, %ava level
coding standard are covered elsewhere.
The intention is that the standards should fit comforta!l with the wa %Developer works and
e:isting applications have !een !uilt ? hopefull man of them are in common use alread
,for e:ample, as a result of developers learning ADF ! studing S)Demo3.
)eferences
@S)A S)Demo Application ? sample application produced ! .racle ,71g onwards3
@T-A The -ltimate "uman )esources Application ,T-")A3 ? sample application developed
in !ook ! 5eter (olet9ke and Duncan #ills ,71.7.B !ased3
@.AA .racle Applications Framework Developer8s $uide ,#etalink BCDE21.7, 71.7.B !ased3
@%"SA %ava "eadstart ? an ADF code generation tool from .racle Consulting ,71.7.B !ased3
@F.DA Fusion .rder Demo ? sample application produced ! .racle ,77g onwards3
Structure of these Standards
These standards are grouped ! topic area for ease of referenceF $eneral ,$3, &ntit .!jects
,&.3, Giew .!jects ,G.3, A#s ,A#3, 'acking 'eans ,''3, Task Flows ,TF3. As a general
rule terms are descri!ed in full e:cept where an a!!reviation is ver well known ,e.g. F(3.
Definitions
This document uses the following definitionsF
Sstem ? the super entit of su!*sstems
Su!*sstem ? a single application such as "), procurement
Application ? snonmous with a su!*sstem, not to !e confused with an ADF
Application /orkspace
Common ADF Application /orkspace ? a single ADF Application /orkspace
encapsulating the common parts of all other Application /orkspaces, such as &.s,
lookup G.s, !ut not Task Flows.
Task Flow ADF Application /orkspace ? a single ADF Application /orkspace
encapsulating the components for a single Task Flow, comprised of !oth #odel H
GiewController projects,
#aster ADF Application /orkspace ? a composite ADF Application /orkspace
reusing Task Flow ADF Application /orkspaces to make a single Application ,see
a!ove3
+ote in the following descriptions an annotation ,D&FA-IT3 is the current %Dev !ehaviour.
$eneral
G1) Application name * ever app must have a short name or acronm that can !e used as
part of package names, specific classes and on paths. This should !e used in lower case for
speed and simplicit ,and to save wearing out the shift ke3. &.g. srdemo, fodemo, um,
foo!ar, speaker
G2) 5ackages should !e prefi:ed ! the client or compan name, though argua!l@7A not a
full Jualified path, e.g. oracle.srdemo, veriton.um, ukoug.speaker.
G3) Framework e:tensions should !e in a separate package@0A, called 6Framework6 perhaps
,called Framework&:tensions in @S)A and frmwke:t in @F.DA3.
G4) 5ut the 'C in a project called #odel ,noteF some places have used Data#odel etc !ut we
suggest using #odel to !e make it clear it8s that part of the #GC architecture3.
G5) Top level 'C directories ? =entities8, =design8 for diagrams, =service8 for application
modules. +oteF the =views8 packages tpicall organised within the individual task flows that
use them ,see later3.
G6) .rganise our directories to suit project lifeccle and source control sstem ,tpicall
Su!version these das3 and li!rar management tools like #aven. &.g. our !uild directories
have to !e outside our trunk folder. &.g.srcKmainKjava, srcKtestKjava folder for unit testing.
Include a =data!ase8folder for our SLI schema creation scripts etc.
Templates
Templates are another significant 77g feature. 4our application should have one or more
templates, though these ma !e imported from an organisation*wide li!rar.
MtodoF need to refine thisN
Application Structure and Task Flows
ADFO%Developer 77g introduces new functionalit called Task Flows. These dramaticall
improve the wa ou use ADF to !uild -Is> modern ADF applications are e:pected to use
them e:tensivel.
4our overall sstem should !e comprised of several Task Flow ADF Application /orkspaces,
each representing a Task Flow modelling a !usiness process, as well as a single Common
ADF Application /orkspace.
A #aster ADF Application /orkspace will include each of the separate Task Flow ADF
Application /orkspaces, in order to meet the overall ApplicationPs needs.
MtodoF a diagram would !e ver useful hereN
Therefore with a new -I project one of the first considerations will !e what task flows are
reJuired.
Task Flows
A task flow is contains a set of -I components which tpicall references the model ,ADF
'C components3 held elsewhere in the application. /ithin a task flow there will !e the usual
GiewController items which should following these guidelinesF
TF1) MtaskflownameN * the GiewController package naming convention as its first part will
reflect the Task Flow nameF eg. createemploees
TF2) MtaskflownameN.view * the code specific to view laer within the GiewController
package will include the su!*package name 6view6 ,D&FA-IT3
TF3) MtaskflownameN.view.!acking * GiewController !acking !eans should go into a su!*
package name 6!acking6. Mref. to AvromPs !log post a!out what is applica!le for !acking
!eansN ,D&FA-IT3
TF4) MtaskflownameN.view.framework ? Mneed clarification from Avrom here N used for
overriden component classes.
TF5) MtaskflownameN.view.pageDefs ? for the ADFm !inding page def files ,D&FA-IT3
TF6) MtaskflownameN.view.servlet ? an servlet, filter or listener code that e:tends the %&&
servlet that is used in generating output. eg. a servlet that dnamicall renders a 'I.' into a
downloada!le file.
TF7) MtaskflownameN.controller * code specific to the controller laer within the
GiewController package will include the su!*package name =controller8
TF8) MtaskflownameN.controller.lifeccle ? code that overrides the ADF controller such as
the &rror"andlerImpl class.
TF9) MtaskflownameN.controller.managed ? GiewController managed !eans should go into a
su!*package name 6managed6
Mref. to AvromPs !log post a!out what is applica!le for managed !eansN Mneed to clarif that
%Dev incorrectl,<3 intermingles term managed !ean and !acking !ean in the ID&N
TF10) MtaskflownameN.controller.servlet * an servlet, filter or listener code that e:tends the
%&& servlet that is used in handling input. eg. a servlet that manages securit !ased on a non*
standard login mechanism.
Giew Controller
VC1) 5ut Giew Controller code in a =GiewController8 project.
VC2) For each ADFm page def file, its name should reflect the we! page it supports with the
suffi: 5ageDef.&g. Giew&mploees5ageDef. ,D&FA-IT3
VC3) The name of each managed !ean should reflect their function, eg. Gersioner or
Cart5rocessor, and not include information a!out its scope etc ,since this can change3.
'acking 'eans
BB1) All !acking !eans should !e in a =!acking8 package
BB2) 'acking !eans should have the same name as the we! page that the are used in, eg.
Giew&mploees.jsp: has a !acking !ean createemploees.view.!acking.Giew&mploees
BB3) 'acking !eans should implement java.io.Seriali9a!le if the application is to !e
deploed on cluster
'C 5rojects
BC1) If ou anticipate having more than around Q1 entities ou should we have separate
model projects for different data su!sstems or application functionalit areas. This allows
developers to concentrate on the model project the are currentl working on. /hen it8s
needed to reuse ADF 'C components !etween different model projects, use the import
functionalit for ADF 'C with %A) files.
'C &ntit .!jects
EO1) &ntities * put associations in an =associations8 su!*package to keep them out of the wa
of the other entities ,which can get Juite a large list anwa3
EO2) For clarit entit names should alwas same as the underling ta!le. Aino suggests
6)eference entities ,and their attri!utes3 are prefi:ed with =Ikp8 for lookup, i.e.
=IkpMentitnameN8. I would suggest for a moderatel si9ed project these should !e in a
separate =lookups8 su!*package.
EO3) Transient attri!utes, calculated on the &., should !e prefi:ed with PTrnsnt6
'C Giew .!jects
VO1) 5ut Giew Iinks in a 6links6 su!*package ,6links6 is in @F.DA, 6viewlinks6 is in @S)A<3
VO2) +ames of Giews * some sort of rule for how to name, e.g. )eadings'#eterGo@7A ,note
the java convention of making onl the first letter upper case, even when an a!!reviation like
G.3. IPve used 6Go6 suffi:, F.Demo has 6G.6 suffi:. Aino suggests 6Gw6 suffi:. If it is a
read*onl G. then rather than use a prefi: or suffi: put it into a su!*package ,e.g.
app.model.view.ro3 to save, sometimes ver difficult, refactoring in case it needs to !e
changed to a )O/ G. later. The same should !e applied to I.G views ? we recommend a
separate package such as app.model.view.lov. The Giews themselves should !e named
according to the functionalitOdata that it provides ,this ma !e Juite far removed from the
underling ta!les for more comple: joins3.
VO3) GiewIink names * if ou have aliases for ta!les and F(s !ased on those the defaults
work prett well I reckon ,I alwas have B char aliases and so an F( might !e
A'CRD&FRF( in which case the view link !ecomes 6A!cDefFkIink63. +ote that view link
names are visi!le through the A# so descriptive ma !e !etter. "owever there has !een
de!ate on this ? some people prefer to invent more descriptive names> it pro!a!l depends on
how data!ase*centric or java*centric our development team is ,and pro!a!l how sensi!l
our foreign kes have !een named in the data!ase too;3.
VO4) Giew.!ject instance names in A# * interesting one * do ou rename or do ou leave
the %Dev default MGiewNMnum!erN< Currentl I rename !ut IPm not sure itPs worth the effort.
VO5) 'undle up Giew .!jects and Giew Iinks into functional su!sstems and package with
task flows if ou are using them.
'C Application #odules
AM1) Application #odule naming * seems to !e nicer to call it MappNService these das.
"ow a!out multiple application modules< "ow a!out nested vs root names<
AM2) If our project is fairl !ig then ou should consider !undling up entities, and possi!l
views, into separate application modules which can then !e nested in our final applications.
MAino suggestsF 6/e group all general read*onl view o!jects that are used for I.GPs and
dropdowns into one application module and nest that into our other A#Ps.6 * worth
considering as a standard practice<N
An &:ample 5roject Structure
As a means of illustrating the application structure here is an e:ample projectF
MtodoF there8s still work to !e done here, especiall wrt. task flowsN
Common ,app.common3
-nitTest ,app.unittest3
Framework ,app.framework3
#odel ,app.model3
app.model.services
app.model.entities
app.model.entities.associations
TaskFlows ,app.tasks3
app.tasks.task7
app.tasks.task7.views
app.tasks.task7.views.viewlinks
app.tasks.task7.!acking
app.tasks.task0
app.tasks.task0.views
app.tasks.task0.views.viewlinks
app.tasks.task7.!acking
app.tasks.taskB
app.tasks.taskB.views
app.tasks.taskB.views.viewlinks
app.tasks.task7.!acking
GiewController ,non*task flow specific -I3
app.ui.!acking
app.ui.utilit
app.ui.pageDefs
+oteF app is the application name, !ut could also !e of the form com.compan.app etc.
Final Comments
TherePs plent more to think a!out ,java, resources, internationalisation3 !ut hopefull this is
a start anwa. At the moment we don8t know of an other pu!licall availa!le ADF coding
standards document e:cept for .A ,which as 71g !ased so doesn8t cover task flows3 and
there still needs to !e an activit of merging in !est practices from that. In addition %"eadstart
ought to enshrine man ADF !est practices so should also !e considered ! this document.
An volunteers would !e most welcome; The intention is that this is a living document that
will evolve with new ADFO%Developer releases and !ecome a resource helpful to the whole
communit.
Footnotes
@7A This point is slightl controversial and has changed over the ears. It has !een fashiona!le
to include a reverse domain name, e.g. uk.co.veriton.um, !ut this has the disadvantage of
making Juite a few nested directories without a clear !enefit, i.e. ou are unlikel to have
other projects in the =com.8 domain as compared to the =com.compan8 domain ,even more so
for countries, like the -(, that have commercial organisations in a su!*domain, e.g.
uk.co.compan3.
@0A Further discussion reJuired ,separate project< * I would reall like a more universall
applica!le one, though as it !ecomes more generic potentiall its value decreases * see the
ADFutils de!ate3
@7A %ohn Flack thinks we should use G. ,and &.3 to save confusion with data!ase views etc