3. IamLUG 2013
Speaker Introduction
• Russell Maher
President, QDiligence / RGM Consulting
Independent Consultant in Chicago area
Exclusively Notes and Domino since 1994
Certified Instructor, Developer, Admin
Spoken 50+ times at LUG and The View events in U.S., Europe
and Australia and IBM Connect 2013
Founded QDiligence in 2010
Commercially hosted multi-tenant XPage SEC compliance
solution
Blogs at XPageTips.com
3
4. IamLUG 2013
Attendee Introduction
• You are an XPager
You have created and deployed actual XPage applications
• You know...
Notes & Domino pretty well
How to create XPages, data sources, custom controls, repeat
controls, etc.
Domino Server-Side JavaScript API well enough to get things
done
• You DO NOT need to know Java™
4
5. IamLUG 2013
First Things First!
• THE CODE!
http://www.rgmconsulting.com/IAmLugCode
You want it…I want you to have it!
• THE SLIDES!
http://www.rgmconsulting.com/IAmLUGSlides
5
6. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
6
7. IamLUG 2013
High Level Concepts
• What is a Managed Bean?
A Serializable Plain Old Java Object (POJO) with a no-argument
constructor, private properties exposed via public getter and
setter methods and configured to a specific scope
• Created in IBM Domino Designer in Java design elements
• How are they used?
Programmatically: To perform the same processing previously
done SSJS
Professionally: To get Java in your fingers and expand your
Java skills
7
8. IamLUG 2013
High Level Concepts
• How are managed beans configured?
Via the faces-config.xml file within the NSF
• How are they deployed?
Right in your NSF!
They are “hot” – no server changes required after updates
• How are they documented?
You add JavaDoc comments
You generate JavaDoc using, you guessed it, a JavaDoc
generator!
Easily produces standard documentation format
8
9. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
9
10. IamLUG 2013
Our First Managed Bean
• Four Steps To Create A Managed Bean
Create the managed bean class
Add private properties with public getters/setters
Configure the managed bean in faces-config.xml
Use your managed bean in an XPage
10
11. IamLUG 2013
Step 1 – Create the Managed Bean Class
• In Domino Designer…
Create a new Java Class Design Element
Set the package as needed
Set the Class name as desired
Select…
Constructors from superclass
Generate comments
Add the java.io.Serializable Interface
Click “Finish”
11
13. IamLUG 2013
Step 1 – Create the Managed Bean Class
• The Results:
A Serializable Java Class with a no-argument constructor
13
14. IamLUG 2013
Step 2 – Add Private Properties With Public Getters/Setters
• Add private properties to your Java class
14
15. IamLUG 2013
Step 2 – Add Private Properties With Public Getters/Setters
• Create methods to get or set those property values
(getters and setters)
Right-click to access context menu
Choose Source – Create getters and Setters…
Select the properties (fields) that need get and/or set methods
Choose a location for the new methods
Click “OK”
15
16. IamLUG 2013
Step 2 – Add Private Properties With Public Getters/Setters
16
17. IamLUG 2013
Step 2 – Add Private Properties With Public Getters/Setters
• New getters/setters will appear in the location you chose
17
18. IamLUG 2013
Step 3 – Configure The Managed Bean In Faces-config.xml
• In Application Configuration locate and edit the faces-
config.xml
• Add configuration markup identifying the managed
bean’s…
Reference name – The name you want to call it by
Java class – The actual Java class
Scope – Application, Session, View, Request or None
18
23. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
23
24. IamLUG 2013
Debugging Managed Beans
• Domino Designer can debug your managed beans
And SSJS in IBM Notes Social Edition
• Three steps to debugging
Start your server in debug mode
Create a debug configuration
Set breakpoints in your code and “listen”
24
25. IamLUG 2013
Starting Your Server In Debug Mode
• Change your server notes.ini file by adding the following:
JavaEnableDebug=1
JavaDebugOptions=transport=dt_socket,server=y,suspend=n,a
ddress=8000
• You will see that your server is ready for Java debug
connections in the server console or log
25
26. IamLUG 2013
Creating A Debug Configuration
• Open a Java design element
• Open the Debug Configurations…
26
27. IamLUG 2013
Creating A Debug Configuration
• Alternatively switch to the Debug Perspective
• Open Debug Configurations…
27
35. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
35
36. IamLUG 2013
When Do Managed Beans Make Sense?
• When there is Complexity
Are you tracking many SSJS
scoped variables?
Do your XPages have complex/progressive
disclosure requirements?
Would the “work item” be better
represented as an “object”?
• When you need Persistence
Persistence = “remembering things for later”
Do you need to track user activity across the entire application?
Does your application require cross-document tracking?
36
37. IamLUG 2013
The Demo Application
• Annual Audits Application
Based on an existing production application
Each year facilities are required to self audit
Audits comprise different areas: Customs, Export, Finance and
others
Each audit “type” has a different set of questions
Each audit type is updated annually
The audit cycle is a 60 day window in Q4
Audits are assigned to individuals
37
38. IamLUG 2013
The Demo Application
• Complexity level is perfect for “beaning”
Multiple audit types
Multiple questions
Multiple users
Annual updates
Hard deadlines
• Persistence is required
User activity needs to be tracked throughout application
We need cross-document access
We need access to the same keywords throughout application
38
40. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
40
41. IamLUG 2013
Basic Java Syntax Rules
• Java is very similar to Server-Side JavaScript
Java is case sensitive
Statements end with a semi-colon;
Most data types are objects
Only a few primitives
Integer (object) vs. int (primitive)
If statements are used for testing
if(x==9) { Do something }
41
42. IamLUG 2013
Basic Java Syntax Rules
• Try/Catch blocks surround methods that “throw”
exceptions
• Methods may or may not return values
42
43. IamLUG 2013
The Bean Rules
• A Plain Old Java Object is considered a bean if it follows
this basic structure
43
private fields
(properties)
No-Argument
Constructor
Operational
methods
Getters/Setters
44. IamLUG 2013
The Bean Rules
• Managed beans should implement the Serializable
interface
• Serialization is the ability to store the state of a Java
object for later use
Removed from memory
Stored typically to disc
Read from disc
Restored into memory
• serialVersionUID value is used to aid verification
during the process
44
45. IamLUG 2013
Adding the Serial Version UID
• Domino Designer will generate the required
serialVersionUID for you if you hover over the class
name
45
47. IamLUG 2013
Before You Bean…Architect Your Solution
• Managed bean flexibility can be a “Bridge to Nowhere”
• Time spent planning architecture is well worth it!
What functions will beans provide?
Reading/writing, emailing, math operations…
What events will be handled by your managed beans?
Saving, editing, approving/not approving…
How many managed beans do you need and what will they do?
Administrative bean, user bean, config bean, audit bean,
utility bean…
What properties and methods will each bean have?
47
48. IamLUG 2013
Annual Audits Application Beans And Classes
48
AdminBean
• Provides Keyword Choices
• Audit Record Maintenance functions
AdminUtils
• Provides static utility
functions to other beans
and classes
AuditBean
• Represents a single
audit in its entirety
AuditUserBean
• Represents the current user
AuditLogBean
• Provides activity logging
to all other beans and classes
AuditQuestion
• Represents a single
audit question
49. IamLUG 2013
Bean Relationships
49
auditUserBean
• First Name
• Last Name
• Full Name
• Administrator?
• Visited home
page?
auditLog Bean
auditQuestion Class
• Format
• Text
• Required?
• Question Key
• Audit Control
Number
• Answer Doc UNID
auditBean
• Year
• Type
• Assigned To
• Key
• Control Number
• Status
auditQuestion
auditQuestion
auditQuestion
50. IamLUG 2013
Annual Audits Architectural Overview
• Question configuration separated from answers
Each config is keyed to a specific annual audit year and type
• Answers are stored in individual documents
One answer = one document
• Audit.xsp repeat control loops through a sorted list of
questions and answers
• Custom controls in the repeat are dynamically bound to
correct answer documents
50
51. IamLUG 2013
Advantages/Disadvantages
• Advantages
Data normalization
Individual answers can be easily maintained through code
The data model lends itself very well to producing data exports,
reports and PDF files
Allows for individualization on a per question basis
Unlimited flexibility for audit creation
• Disadvantages
A lot of documents
A little more code
Missing answer documents are fatal
51
52. IamLUG 2013
Audit Bean Task #1 – Set Basic Audit Information
• Audit.xsp uses the AuditBean properties for audit
information display
Title of the audit
The name of the current user
Audit record control number
Any other information that is audit-specific
52
54. IamLUG 2013
Audit Bean Task #2 – Building The Questions
• Next up, the AuditBean creates a list of all the questions
for this audit
The list of questions is sorted by key
Each question is represented as an auditQuestion object
auditQuestion properties:
Format of the question
Question text
Whether it is required
Question key
UNID of the associated answer document
54
55. IamLUG 2013
Java TreeMaps
• Java has a wonderful object called a TreeMap
Perfect for tracking auditQuestion objects
• Java TreeMaps…
Sort themselves automatically
Are comprised of MapEntry objects
Each MapEntry object has a key and a value
55
57. IamLUG 2013
Connecting the Audit Record to an Audit
• Audit Records contain information about the year and
type of audit
• Audits are represented by an AuditBean instantiated
before the audit is accessed
• AuditBean initialization method called from a link in the
audit records view
• AuditBean built before audit.xsp is opened
57
60. IamLUG 2013
How Audit.xsp Works
• When auditPage.xsp opens…
Repeat Control accesses the AuditBean
Loops through the TreeMap of auditQuestion objects
Automatically sorted in question order for this specific year
and audit type
A questionControl Custom Control is repeated once for every
auditQuestion object
The questionControl contains:
Document data source
Question Text
Custom controls for different answer formats (Radio, Text)
Everything the questionControl needs to know about the
current question is contained in the auditQuestion object
60
62. IamLUG 2013
Sharing Data Between Managed Beans
• Sharing data between beans is very common
Why duplicate information when you can just go read it?
• Several ways to do this:
“Note Passing” via the sessionMap
Bean injection and managed properties
One managed bean can be a property of another managed
bean
62
63. IamLUG 2013
Using the SessionMap To Share Data
• The sessionMap is a Java Map
Objects accessible by a key value
You already use this when you write sessionScope.put(“x”,5)
• Utility functions can be used to read from/write to the
sessionMap
Handy mechanism especially since all of your sessionScoped
managed beans exist in the sessionMap
Does require you to keep track of the scoped variables being
passed around
Documentation anyone?
63
65. IamLUG 2013
Using Managed Properties
• Managed beans can be configured to have default values
for their properties
• Set in the faces-congif.xml
65
66. IamLUG 2013
Using A Managed Bean As A Managed Property
• Managed beans often have properties that are Java
objects
questionsList property of AuditBean is a TreeMap
• A managed property can have a default value that is
another managed bean
66
68. IamLUG 2013
Agenda
• High Level Concepts
• Our First Managed Bean
• Debugging Managed Beans
• When Do Managed Beans Make Sense?
• Building The Audit Bean
• Q & A
68
69. IamLUG 2013
Q & A
• Questions?
• ¿Preguntas?
• Domande?
• Haben Sie Fragen?
• 有问题吗?
• Spørsmål?
• Spørgsmål?
• 質問はありますか?
69
70. IamLUG 2013
Recommended Resources
• The BalusC Code
EXCELLENT resource on Java and JSF!
http://balusc.blogspot.com/
• StackOverflow
http://StackOverflow.com
• Code Ranch
JSF Forum - http://www.coderanch.com/forums/f-82/JSF
Active discussion on All Thinge JSF and Java
• NotesIn9
http://NotesIn9.com
70