2. Speaker Introduction
Russell Maher – President, QDiligence and RGM Consulting
– Independent Consultant in Chicago area
– Exclusively Notes and Domino since 1994
• Certified Instructor, Developer, Administrator
– Spoken 50+ times at LUG and The View events in U.S., Europe and Australia
• Plus…XPages Bootcamp, Advanced XPages Bootcamp
– Founded QDiligence in 2010
• Commercially hosted multi-tenant XPage SEC compliance solution
– Blogs at XPageTips.com
2
3. 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™
3
4. First Things First!
Why are we here today?
– We are learning how, when and why to use managed beans in your XPage applications
– This is a Master Class with an emphasis on “class”
• Lots of complete working code
• Lots of explanation about each step
• Enough Java instruction for you to add “Java Developer” to your resume
THE CODE!
– http://www.rgmconsulting.com/TheCode
– You want it…I want you to have it!
– http://www.rgmconsulting.com/TheSlides
4
6. 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
– Yep, it’s Java!
Where are they created?
– Right in IBM Domino Designer!
– 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
6
7. 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?
– JavaDoc
– You add JavaDoc comments
– You generate JavaDoc using, you guessed it, a JavaDoc generator!
– Easily produces standard documentation format
7
9. Your First Managed Bean
Four Steps To Create A Managed Bean
1. Create the managed bean class
2. Add private properties with public getters/setters
3. Configure the managed bean in faces-config.xml
4. Use your managed bean in an XPage
9
10. 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”
10
12. Step 1 – Create the Managed Bean Class
The Results: A Serializable Java Class with a no-argument constructor
12
13. Step 2 – Add Private Properties With Public Getters/Setters
Add private properties to your Java class
13
14. 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”
14
15. Step 2 – Add Private Properties With Public Getters/Setters
15
16. Step 2 – Add Private Properties With Public Getters/Setters
Your new getters/setters will appear in the location you chose
16
17. 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
– Java class
– Scope
– Example:
<managed-bean>
<managed-bean-name>myFirstBean</managed-bean-name>
<managed-bean-class>com.rgm9.FirstBean</managed-bean-class>
<managed-bean-scope>session</managed-bean-scope>
</managed-bean>
17
18. Step 3 – Configure The Managed Bean In Faces-config.xml
18
19. Step 4 – Use Your Managed Bean In An XPage
Connect to your managed bean using…
– Expression Language (EL)
19
20. Step 4 – Use Your Managed Bean In An XPage
Connect to your managed bean using…
– Managed bean public methods
20
23. 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?
23
24. 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
24
25. 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
25
28. 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 }
28
29. Basic Java Syntax Rules
Try/Catch blocks surround methods that throw exceptions
Methods may or may not return values
29
30. JavaDoc Comment Rules
In order to generate JavaDoc later you need to add JavaDoc comments now
Best practice is to comment as you go
Basic JavaDoc Rules
– JavaDoc is written in HTML
– Comments start with /** and end with */
– The JavaDoc comment must immediately precede the code being documented
• Class, method, field/property, package
– The first line of text until a period and a space is converted into the description
• All text after that appears in the summary
– Specific tags are used
• @author, @version, @param, @return
30
31. Adding JavaDoc Comments
Click in the method you want to comment
ALT + Shift + J is the keyboard shortcut to insert a JavaDoc comment
Example:
31
32. The Bean Rules
A Plain Old Java Object is considered a bean if it follows this basic structure
private fields
(properties)
No-Argument
Constructor
Operational
methods
Getters/Setters
32
33. 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
33
34. Adding the Serial Version UID
Domino Designer will generate the required serialVersionUID for you if
you hover over the class name
34
36. Before You Bean…Architect Your Solution
If you are beaning your XPage, chances are there is complexity
Using managed beans provides a great deal of flexibility
Spending time to plan your architecture is well worth the effort
Questions to ask:
– 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…
– Exactly what properties and methods will each bean have
36
37. Annual Audits Application Beans And Classes
AdminBean AdminUtils UserBean
• Provides Keyword Choices • Provides static utility • Represents the current user
• Audit Record Maintenance functions functions to other beans
and classes
LogBean AuditQuestion AuditBean
• Provides activity logging • Represents a single • Represents a single
to all other beans and classes audit question audit in its entirety
37
38. Bean Relationships
auditBean auditQuestion Class
auditUserBean Year
•
• Format
• First Name • Type
Assigned To • Text
• Last Name •
• Key • Required?
• Full Name Control Number
• • Question Key
• Administrator? • Status
• Audit Control
• Visited home
Number
page? auditQuestion
• Answer Doc UNID
auditQuestion
auditLog Bean auditQuestion
38
39. Annual Audits Architectural Overview
Question configuration records are separate from answers
– Each config is keyed to a specific annual audit year and type
Answers are stored individual documents
– One answer = one document
Audit.xsp uses a repeat control to traverse a sorted list of questions and
answers
– The list is created each time the AuditBean used
Custom controls within the repeat are dynamically bound to the correct
answer documents
39
40. 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
40
41. 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
41
43. 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
43
44. 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
44
46. 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
The AuditBean initialization method needs to be called from the a link in the
audit records view
Builds the AuditBean before the audit.xsp is even opened
46
49. How Audit.xsp Works
When audit.xsp opens…
– Its 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
49
51. Sharing Data Between Managed Beans
In a complex application sharing data between beans is very common
– Why duplicate information when you can just go read it?
There are several ways to do this:
– A managed bean can simply instantiate another Java class
• This is technically not between beans but bears mentioning
– The sessionMap can be used as a global “note passing” mechanism
• One bean writes something to the sessionMap (sessionScope)
• Other beans read that information from the sessionMap
– Bean injection and managed properties
• One managed bean can be a property of another managed bean
51
52. 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 created 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?
52
54. Using Managed Properties
Managed beans can be configured to have default values for their properties
Set in the faces-congif.xml
54
55. Using A Managed Bean As A Managed Properties
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
55
58. Debugging Managed Beans
Domino Designer can debug your managed beans
– And other Java
– And SSJS in IBM Notes Social Edition
Three steps to debugging
1. Start your server in debug mode
2. Create a debug configuration
3. Set breakpoints in your code and “listen”
58
59. 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,address=8000
You will see that your server is ready for Java debug connections in the
server console or log
59
60. Creating A Debug Configuration
Open a Java design element
Open the Debug Configurations…
60
61. Creating A Debug Configuration
Alternatively switch to the Debug Perspective
Open Debug Configurations…
61
62. Creating A Debug Configuration
Create a new debug configuration
62
63. Creating A Debug Configuration
Configure the debug configuration by adding or ensuring the Project name
includes your NSF
63
70. Generating JavaDoc
JavaDoc documentation is generated from your JavaDoc comments
Domino Designer does not ship with a JavaDoc generator
JavaDoc configuration steps
– Install the JDK of your choice
– Install Eclipse
– Create a new Java Project in Eclipse
70
71. Generating JavaDoc
JavaDoc generation steps:
1. Export your managed bean code to the Eclipse project folder
2. Open Eclipse and refresh your project if necessary to see the newly exported source
code
3. In Eclipse choose Project – Generate JavaDoc…
71
72. Generating JavaDoc
JavaDoc generation steps…
(continued)
4. Complete the fields as needed
5. Click “Finish”
72
73. Generating JavaDoc
JavaDoc generation steps…
(continued)
6. Your JavaDoc will be added to your Eclipse Java Project
73
74. Generating JavaDoc
Open the index.html file in a browser to see your JavaDoc in all its fully
commented and correctly documented glory!
74
76. Recommended Resources
The BalusC Code
– EXCELLENT resource on Java and JSF!
– http://balusc.blogspot.com/
StackOverflow
– http://StackOverflow.com
– Your questions has already probably been answered
Code Ranch
– JSF Forum - http://www.coderanch.com/forums/f-82/JSF
– Active discussion on All Thinge JSF and Java
NotesIn9
– http://NotesIn9.com
– Free XPages videos. Lots of them!
76
77. Related Sessions
Master Class: XPages Performance - Inside Out
– JMP401 Today 1:30 – 3:30 Swan Pelican 1-2
– Tony McGuckin, Maire Kehoe
IBM Lotus Domino XPages Performance in a Nutshell
– AD 208 Tuesday 10:00 AM – 11:00 AM Dolphin S. Hemisphere IV – V
– Maire Kehoe, Tony McGuckin
77