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 –  Be consistent –  Be consistent

Image: David Castillo Dominici / FreeDigitalPhotos.net

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

•  ADF Structures •  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

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

Master Workspace ViewController

The Sum-of-the-Parts Architecture Common Workspace

Entity Objects

View Objects

AppModule

Framew

xtensions

Task Flow Templates

Unbounded Task Flow

BTF Workspace ViewController

Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

Page Templates

Declarative Components

ViewController Extensions

Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

ADF Libraries

F Libraries

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

Master Workspace ViewController

The Sum-of-the-Parts Architecture Common Workspace

Entity Objects

View Objects

AppModule

Framew

xtensions

Task Flow Templates

Unbounded Task Flow

Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

Page Templates

Declarative Components

ViewController Extensions

Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

ADF Libraries

F Libraries

Master Workspace

The Sum-of-the-Parts Architecture Common Workspace BTF Workspace BTF Workspace

ADF Libraries

F Libraries

Master Workspace

The Sum-of-the-Parts Architecture

Common Workspace BTF Workspace BTF Workspace

Hr Workspace

The Sum-of-the-Parts Architecture

Common Workspace Emp 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

•  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

Common

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

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

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 –  ViewController/public_html/WEB-INF

•  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/WEB-INF –  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

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.....

oracle adf architecture tv - development - naming conventions & project layouts

oracle andor

adf naming

general naming conventions

good naming conventions

following naming conventions

project layout conventions

different preferences

adf objects

Technology

successful modernization with adf / adf mobile

mike dean• adf business components (adf bc) • adf faces...

adf educators guide to healthy eating (adf edge) · adf...

build rich client forms with adf swing and adf business...

oracle adf architecture tv - design - adf service...

adf-14 the role of adf in private sector development adf14...

adf naming and project layout guidelines v2.00...

adf-14 financing framework · adf-10 adf-11 adf-12 adf-13...

adf power tuning power tuning 2017-12-14... ·...

adf naming and project layout guidelines v2.00 … naming...

oracle adf architecture tv - design - architecting for adf...

adf gci - oecd · adf gci evaluation evaluation evaluation...

oracle adf architecture tv - design - adf reusable artifacts

oracle adf architecture tv - design - advanced adf task flow...

adf design fundamentals using javascript in adf faces rich...

goodbye nightmare: tips and tricks for creating complex...

adf naming and project layout guidelines v1.00...

oracle adf architecture tv - design - adf architectural...

scm: adf release notes · adf 2006.01..... 41

aom-145/1114-32 - section 2-18 - navigation and ......−...