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

1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.


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

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



•  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


1

Master Workspace ViewController

The Sum-of-the-Parts Architecture Common Workspace

Model

Entity Objects

View Objects

AppModule

Framew

ork E

xtensions

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


Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

ADF Libraries

AD

F Libraries

EA

R

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


1

Master Workspace ViewController

The Sum-of-the-Parts Architecture Common Workspace

Model

Entity Objects

View Objects

AppModule

Framew

ork E

xtensions

Task Flow Templates

Unbounded Task Flow

Pages


Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

Page Templates

Declarative Components

Skins

ViewController Extensions


Bounded Task Flow

Fragments

Bounded Task Flow

Fragments

ADF Libraries

AD

F Libraries

EA

R


1

Master Workspace

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

ADF Libraries

AD

F Libraries

EA

R


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




Common Emp

Dept




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


Further Reading

•  ADF Naming & Project Layout Guidelines –  http://bit.ly/adfarchsquare

•  Sten Vesterli’s Oracle ADF Enterprise Application Development Made Simple


Technology

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