Oracle ADF Architecture TV - Development - Naming Conventions & Project Layouts

Real World ADF Design & Architecture Principles
Naming Conventions & Project Layouts
15th Feb 2013 v1.0

Learning Objectives
•  At the end of this module you should be able to:
–  Recognize the needs for naming and project layout conventions
–  Identify some of the challenges the conventions attempt to avoid
–  Appreciate the conventions aren't the law, you can define your own
Image: imagerymajestic/ FreeDigitalPhotos.net

Program Agenda
•  The Need for Guidelines
•  General Guidelines
•  JDeveloper Workspaces & Projects
–  Workspaces
–  Projects
•  ADF Structures

Code Naming and Project Layout Guidelines
•  Such guidelines for code can assist:
–  Readability
–  Maintainability
–  Avoid namespace collisions
–  Show a well disciplined development team
Image: Bernie Condon / FreeDigitalPhotos.net

Guidelines for Following Naming Conventions
•  Naming Conventions are just “conventions”, they are not the law
•  Violations don’t result in jail time!
•  Different people and projects have different preferences
•  Oracle breaks their own conventions all the time (shhhh!)
•  If you do break them:
–  Document why
–  Be consistent
Image: David Castillo Dominici / FreeDigitalPhotos.net

7 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.7 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
You may be building one monolithic
but simple application today, but
tomorrow you may have dozens of
workspaces containing reusable
templates, task flows, skins, business
logic.
Keep an eye on the future.
Without good naming conventions
and project structures, things are
going to get messy quickly.
Image: Ambro / FreeDigitalPhotos.net

Code Naming and Project Layout Guidelines
•  Oracle will now introduce it’s
233 guidelines
•  Guideline #1 of 233……
•  Understandably reading all of
these can be rather tedious
work

Further Reading
•  Rather than discuss all 233 points
•  You’re referred to a paper that covers
these in detail
–  ADF Naming and Project Layout Guidelines
–  http://bit.ly/adfarchsquare
–  The conventions are suggestions from
Oracle
–  With the goal of shortcutting writing your own
–  But you can go with your own
•  Here we’ll discuss the salient points
•  And base it on a known architectural
pattern

Program Agenda
–  Workspaces
–  Projects
•  Deployment Artifacts

General Naming Conventions for ADF
•  Follow the Java SE naming conventions
•  http://bit.ly/javasecodeconvsect9
•  Conventions should extend to ADF objects too

Hungarian Notation
•  Hungarian Notation is a code convention of
adding prefix/suffixes to objects to designate
their type
–  eg. TBL_EMPLOYEES for a database table
•  Can lead to inconsistent names when objects
change type and refactoring isn’t possible
•  Use only when objects can’t change type or
that’s the known general convention
–  eg. EmployeesView for ADF BC view objects

Use Meaningful Names, Acronyms & Abbreviations
•  Names should be meaningful when taken out of context
–  eg. Csp400.jspx means little, EnrolStudent.jspx is meaningful
•  Avoid using abbreviations and conventions from legacy systems
•  Avoid unnecessary acronyms/abbreviations
–  eg. Dob for DateOfBirth
•  Use acronyms/abbreviations when the acronym is used more
commonly than the complete word/phrase
–  eg. Html rather than HyperText Markup Language
•  If a name contains an acronym, only capitalize the first letter of the
acronym
–  eg. RegisteredTfn for Registered Tax File Number

Java Classes, Abstract Classes & Interfaces
•  Use nouns – cat, dog, house, queue, shopping cart
•  Mixed case, 1st letter of each word capitalized, no special characters
•  Keep class names simple as possible
•  Use whole words, avoid acronyms and abbreviations
–  Unless the abbreviation is more widely used than word e.g. HTML
•  e.g. Raster, EmployeeEntitlements, Departments
•  Treat ADF objects the same as Java Classes for naming purposes

Program Agenda
–  Workspaces
–  Projects

Describes guidelines based
around an ADF Architectural
Pattern out of the “Angels in the
Architecture” presentation from
Oracle Open World 2013
http://youtu.be/toEuQvp73h8

1Master Workspace
ViewController
The Sum-of-the-Parts Architecture
Common Workspace
Model
Entity Objects
View Objects
AppModule
Framework
Extensions
Task Flow Templates
Unbounded Task Flow
Pages
BTF Workspace
ViewController
Bounded Task Flow
Fragments
Bounded Task Flow
Fragments
Page Templates
Declarative Components
Skins
ViewController
Extensions
BTF Workspace
ViewController
Bounded Task Flow
Fragments
Bounded Task Flow
Fragments
ADF Libraries
ADFLibraries
EAR
For
purposes
of
the
following
discussion
let’s
assume

1)  There
is
a
single
database
schema
“humanres”

2)  The
BTF
workspaces
separately
deal
with

Departments
and
Employees
funcBons
within
our

applicaBon

3)  The
overall
applicaBon
being
built
is
for
HR

1Master Workspace
ViewController
Common Workspace
Model
Entity Objects
View Objects
AppModule
Framework
Extensions
Task Flow Templates
Unbounded Task Flow
Pages
BTF Workspace
ViewController
Bounded Task Flow
Fragments
Bounded Task Flow
Fragments
Page Templates
Declarative Components
Skins
ViewController
Extensions
BTF Workspace
ViewController
Bounded Task Flow
Fragments
Bounded Task Flow
Fragments
ADF Libraries
ADFLibraries
EAR

1Master Workspace
Common WorkspaceBTF Workspace BTF Workspace
ADF Libraries
ADFLibraries
EAR

Master Workspace
Common WorkspaceBTF Workspace BTF Workspace

Hr Workspace
Common WorkspaceEmp Workspace Dept Workspace

Challenges
•  At least 4 workspaces (if not many more)
•  Workspaces contain multiple projects
•  Require their own package structures
•  1 to many bounded task flows requiring unique namespaces
•  Generate numerous ADF Libraries to be consumed
•  We must not have naming collisions
•  Programmers should not get confused where code is coming from
•  There’s potential for more applications in the future

Program Agenda
–  Workspaces
–  Projects

•  The location of code across developer’s PC can be different
•  However it helps to standardize this
•  In case the developer is run over by a bus
•  Build scripts need to assume a standard location
•  Exemptions need to be put in place for virus scanners

•  All workspaces regardless of their purpose should prefix
the default package with your organization’s URL (in
reverse)
•  This helps differentiate your organization’s code from
others, both if you’re importing or exporting code

•  Ensure workspace names are unique amongst
all workspaces
•  A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts

all workspaces
Common

all workspaces
Common
Emp

all workspaces
Common
Emp
Dept

all workspaces
Common
Emp
Dept
Hr

•  Also use meaningful names
•  e.g. VehicleLicensingSystem or Procurement
•  But use acronyms or abbreviations if possible: Vls, Proc
•  The workspace name becomes basis for default package
•  Long names can make the package structure unwieldy
Common
Emp
Dept
Hr

•  For common artifacts place in a workspace with
a “Common” prefix
•  In this example there is only 1 Common workspace which
will contain many projects
•  Alternatively you may break this into 1 workspace per
project, so the following naming scheme could be used
•  eg. CommonModel or CommonViewController
Common
Emp
Dept
Hr

•  For task flows workspaces use a suffix like
“Modules” or “Flows”
•  Suffix might depend on how many task flows are
contained in the workspace
•  eg. HrModule or ProcureLodgingsFlow
Common
Emp
Dept
Hr

•  For the main application use just the application
name
Common
Emp
Dept
Hr

Common
Emp
Dept
Hr
•  You eventually may have 10s/100s of workspaces
•  Use subdirectories to your advantage to
categorize types of workspaces.
•  e.g. Common, Flow, Applications
•  Categories can assist division of source control
directory structures

Common
Emp
Dept
Hr
•  The same rule applies to your package names
•  Ensure categorizations comes before name to
assist sorting

Common
Emp
Dept
Hr
•  The workspace name and case should be consistent as the base directory for
the workspace and the .jws file
•  Avoids confusion and errors
•  In discussing source code
•  When copying files
•  Comparing source code to SVN
•  Working with build tools

Program Agenda
–  Workspaces
–  Projects

Projects
•  The project name and case should be consistent as the base directory for
the project and the .jpr file
•  Project names should attempt to follow defaults proposed by the JDev
wizards
•  e.g. Model and ViewController
•  These are familiar to programmers and new team members with ADF experience
•  There are some exceptions (see next slide)
•  Ensure unique projects names per workspace (enforced anyway)
•  But they don’t need to be unique across workspaces

ADF Business Component Projects
•  ADF BC projects at design time are limited to a single database
connection defined in the Project Properties
•  However some applications/architectures must support multiple
database schemas, each served by a different Model project
•  In this case break the previous convention to include a prefix of the
schema name in the Model project name
–  e.g. HrModel

Project Default Packages
•  On multi workspace applications, it’s important to ensure unique
packages across workspaces
•  Regardless or your architecture use this for future proofing
•  The default package for a project should take the form:
<org>.<workspace-type>.<workspace-name>.<project-name>
•  eg. com.acme.common.hrmodel
com.acme.flow.createemployee.view
com.acme.app.procurement.model

Program Agenda
–  Workspaces
–  Projects

Hr Workspace
Reminder: Example Package Structures
Common Workspace
Emp Workspace Dept Workspace
com.acme.common.model
com.acme.flow.emp.view
com.acme.flow.dept.view
com.acme.app.hr.view

Object Package Example
Model.jpx file Resides in base package for project com.acme.common.model.adfbc.Model.jpx
Framework extensions .base com.acme.common.model.adfbc.base.HrAppModuleImpl.java
Application modules .services com.acme.common.model.adfbc.services.HrAppModule
Domains .domains com.acme.common.model.adfbc.domains.EmailDomain
Entity objects .entities com.acme.common.model.adfbc.entities.Employees
Entity associations .entities.associations com.acme.common.model.adfbc.entities.associations.EmpDeptFkAssoc
Property sets .properties com.acme.common.model.adfbc.properties.ReadOnlyPropertySet
Validation rules .validations com.acme.common.model.adfbc.validations.EmailValidationRuleImpl.java
Updateable view objects .views com.acme.common.model.adfbc.views.EmployeesView
Read only view objects .views.readonly com.acme.common.model.adfbc.views.readonly.PostcodesView
Programmatic view objects .views.programmatic com.acme.common.model.adfbc.views.programmatic.SocialSecurityView
View links .views.links com.acme.common.model.adfbc.views.links.EmpDeptFkLink
ADF BC Package Structures

ADF ViewController BTF Structure Challenge
•  Base BTF workspace package examples:
–  com.acme.flow.dept.view or com.acme.flow.dept.view
•  JDeveloper by default places
–  BTFs under ViewController/public_html/WEB-INF
–  Page/fragments under ViewController/public_html
•  But
–  PageDefs under ViewController/adfmsrc/com/acme/flow/dept/view
–  Beans under ViewController/src/com/acme/flow/dept/view
•  By the structures alone this makes it hard to relate the code artifacts

ADF ViewController BTF Structure Solution
•  Use the same directory structure for all artifacts. e.g.:
–  BTFs:
•  ViewController/public_html/WEB-INF/
com/acme/flow/dept/view/depttaskflow/depttaskflow.xml
–  Page/Fragments
•  ViewController/public_html/
com/acme/flow/dept/view/depttaskflow/ViewDept.jspx
–  PageDefs
•  ViewController/adfmsrc/
com/acme/flow/dept/view/depttaskflow/PageDef/ViewDeptPageDef.xml
–  Beans
•  ViewController/src/
com/acme/flow/dept/view/depttaskflow/DeptBean.java

ADF ViewController UTF Structure Challenge
•  Base UTF workspace package example:
–  com.acme.app.hr.view
•  adfc-config.xml file(s) must reside under
–  ViewController/public_html/WEB-INF
•  JDeveloper will still place
–  Page/Fragments under ViewController/public_html
•  But
–  PageDefs under ViewController/adfmsrc/com/acme/flow/dept/view/PageDef
–  Beans under ViewController/src/com/acme/flow/dept/view
•  Argh! We cannot apply our BTF directory solution here

ADF ViewController UTF Structure Challenge
•  Base UTF workspace View Controller package example:
–  com.acme.app.hr.view
•  adfc-config.xml file(s) must reside under
•  JDeveloper will still place
–  Pages under ViewController/public_html
•  But
–  PageDefs under ViewController/adfmsrc/com/acme/app/hr/view/PageDef
–  Beans under ViewController/src/com/acme/app/hr/view
•  Argh! We cannot apply our BTF directory solution here

ADF ViewController UTF Structure Solution
•  Instead assume that:
–  ViewController/public_html
–  ViewController/adfmsrc/com/acme/app/hr/view/
–  ViewController/src/com/acme/app/hr/view/
•  Are all logical “base” structures for all your different UTF artifacts
•  This is where you expect to find your UTF artifacts
•  So you don’t need to move anything around
•  You just assume that any code artifact at these levels are related

Options to Avoid BTF Namespace Solutions
•  Use path with project package name preceding BTF name
–  e.g. /WEB-INF/com/acme/flows/emp/viewcontroller/view/
CreateEmployees.xml#CreateEmployees
–  Can be long and unwieldy in the IDE
•  Use path with workspaces name preceding BTF name
–  e.g. /WEB-INF/EmpFlows/CreateEmployees.xml#CreateEmployees
–  Relies on assumption workspace names are unique

Program Agenda
–  Workspaces
–  Projects

But Oracle’s hasn’t covered
every type of component –
what about static VOs?!!
What do we do?
Exercise

But Oracle’s conventions are
completely different from ours!
What do we do?
Exercise

One of Oracle's guidelines is
different from ours!
What do we do?
Exercise

But we don't like one of
Oracle's guidelines!
What do we do?
Exercise

Conclusion
•  Conventions show a well disciplined development team
•  They are necessary to avoid namespace collisions in large scale application
development
•  However conventions aren't the law, you can bend the rules and write your
own
•  Document, document, document.....

Further Reading
•  ADF Naming & Project Layout Guidelines
–  http://bit.ly/adfarchsquare
•  Sten Vesterli’s Oracle ADF Enterprise Application Development Made Simple

Oracle ADF Architecture TV - Development - Naming Conventions & Project Layouts

More Related Content

What's hot

Viewers also liked

Similar to Oracle ADF Architecture TV - Development - Naming Conventions & Project Layouts

Recently uploaded

Oracle ADF Architecture TV - Development - Naming Conventions & Project Layouts