oracle adf architecture tv - development - naming conventions & project layouts
DESCRIPTION
Slides from Oracle's ADF Architecture TV series covering the Development phase of ADF projects, a discussion on naming and project layout conventions for your ADF projects. Like to know more? Check out: - Subscribe to the YouTube channel - http://bit.ly/adftvsub - Development Playlist - http://www.youtube.com/playlist?list=PLJz3HAsCPVaQfFop-QTJUE6LtjkyP_SOp - Read the episode index on the ADF Architecture Square - http://bit.ly/adfarchsquareTRANSCRIPT
1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
2 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
3 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
4 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
5 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
6 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
8 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
Image: David Castillo Dominici / FreeDigitalPhotos.net
9 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
10 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures • Deployment Artifacts
11 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
General Naming Conventions for ADF
• Follow the Java SE naming conventions • http://bit.ly/javasecodeconvsect9 • Conventions should extend to ADF objects too
Image: David Castillo Dominici / FreeDigitalPhotos.net
12 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
13 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
14 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
15 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
16 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 16 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
17 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 17 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
BTF Workspace ViewController
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
18 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 18 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
BTF Workspace ViewController
Bounded Task Flow
Fragments
Bounded Task Flow
Fragments
ADF Libraries
AD
F Libraries
EA
R
19 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 19 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
1
Master Workspace
The Sum-of-the-Parts Architecture Common Workspace BTF Workspace BTF Workspace
ADF Libraries
AD
F Libraries
EA
R
20 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 20 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Master Workspace
The Sum-of-the-Parts Architecture
Common Workspace BTF Workspace BTF Workspace
21 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 21 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Hr Workspace
The Sum-of-the-Parts Architecture
Common Workspace Emp Workspace Dept Workspace
22 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
23 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
24 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 24 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
25 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 25 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
26 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 26 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
27 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 27 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• 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
28 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 28 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• 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
29 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 29 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Ensure workspace names are unique amongst all workspaces • A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts
30 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 30 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Ensure workspace names are unique amongst all workspaces • A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts
Common
31 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 31 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Ensure workspace names are unique amongst all workspaces • A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts
Common Emp
32 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 32 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Ensure workspace names are unique amongst all workspaces • A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts
Common Emp
Dept
33 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 33 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• Ensure workspace names are unique amongst all workspaces • A good choice of workspace names helps differentiate many
workspace artifacts from other workspace artifacts
Common Emp
Dept Hr
34 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 34 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• 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
35 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 35 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• 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
36 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 36 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• 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
37 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 37 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
• For the main application use just the application name
Common Emp
Dept Hr
38 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 38 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
39 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 39 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Common Emp
Dept Hr
• The same rule applies to your package names • Ensure categorizations comes before name to
assist sorting
40 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 40 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
41 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
42 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
43 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
44 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
45 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
46 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 46 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
47 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 47 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
48 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
49 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
50 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
51 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
52 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
53 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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
54 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Program Agenda
• The Need for Guidelines • General Guidelines • JDeveloper Workspaces & Projects
– Workspaces – Projects
• ADF Structures
55 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 55 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
But Oracle’s hasn’t covered every type of component – what about static VOs?!!
What do we do?
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
56 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 56 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
But Oracle’s conventions are completely different from ours!
What do we do?
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
57 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 57 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
One of Oracle's guidelines is different from ours!
What do we do?
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
58 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. 58 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
But we don't like one of Oracle's guidelines!
What do we do?
Exercise
Image: imagerymajestic/ FreeDigitalPhotos.net
59 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
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.....
60 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.
Further Reading
• ADF Naming & Project Layout Guidelines – http://bit.ly/adfarchsquare
• Sten Vesterli’s Oracle ADF Enterprise Application Development Made Simple
61 Copyright © 2013, Oracle and/or its affiliates. All rights reserved.