JMP402 Master Class: Managed beans and XPages: Your Time Is Now

© 2013 IBM Corporation

JMP402 Master Class: Managed Beans and XPages: Your Time Is Now Russell Maher | President, QDiligence and RGM Consulting

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

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

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

First Things First!

4

5 © 2013 IBM Corporation

Agenda

High Level Concepts

Our First Managed Bean

When Do Managed Beans Make Sense?

Building The Audit Bean

Debugging Managed Beans

Generating JavaDoc

Q & A

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

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


Agenda

High Level Concepts





Generating JavaDoc

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

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


11


The Results: A Serializable Java Class with a no-argument constructor

12

Step 2 – Add Private Properties With Public Getters/Setters

Add private properties to your Java class

13


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


Your new getters/setters will appear in the location you chose

16

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

Step 3 – Configure The Managed Bean In Faces-config.xml

18

Step 4 – Use Your Managed Bean In An XPage

Connect to your managed bean using…

– Expression Language (EL)

19

Step 4 – Use Your Managed Bean In An XPage

Connect to your managed bean using…

– Managed bean public methods

20

Creating A “First” Managed Bean

21


Agenda

High Level Concepts





Generating JavaDoc


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

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

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

Annual Audits Application

26


Agenda

High Level Concepts





Generating JavaDoc

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

Basic Java Syntax Rules

Try/Catch blocks surround methods that throw exceptions

Methods may or may not return values

29

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

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

The Bean Rules

A Plain Old Java Object is considered a bean if it follows this basic structure

32

private fields (properties)

No-Argument Constructor

Operational methods

Getters/Setters

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

Adding the Serial Version UID

Domino Designer will generate the required serialVersionUID for you if you hover over the class name

34

Creating The Audit Bean Class

35

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

Annual Audits Application Beans And Classes

37

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

UserBean • Represents the current user

LogBean • Provides activity logging

to all other beans and classes

AuditQuestion • Represents a single

audit question

Bean Relationships

38

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

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

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

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

AuditBean Step #1 – Setting Basic Audit Information

42

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

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

AuditBean Step #3 – Building The Questions

45

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

Path From Link To Audit

47

Connecting The Audit Record To The AuditBean

48

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

Creating Audit.xsp

50

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

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

SessionMap Utility Functions

53

Using Managed Properties

Managed beans can be configured to have default values for their properties

Set in the faces-congif.xml

54

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

Sharing Managed Bean Data

56


Agenda

High Level Concepts





Generating JavaDoc


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

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

Creating A Debug Configuration

Open a Java design element

Open the Debug Configurations…

60


Alternatively switch to the Debug Perspective

Open Debug Configurations…

61


Create a new debug configuration

62


Configure the debug configuration by adding or ensuring the Project name includes your NSF

63

Add Breakpoints To Your Managed Bean

64

Now Go Forth And Debug!

Connect to the server using your debug configuration

65

Run Your Code

After executing your code you may see this prompt to switch to the Debug Perspective

66

Run Your Code

The Debug Perspective provides the debugging functionality

67

Debugging The AuditBean

68


Agenda

High Level Concepts





Generating JavaDoc

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

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

Generating JavaDoc

JavaDoc generation steps… (continued)

4. Complete the fields as needed

5. Click “Finish”

72

Generating JavaDoc

JavaDoc generation steps… (continued)

6. Your JavaDoc will be added to your Eclipse Java Project

73

Generating JavaDoc

Open the index.html file in a browser to see your JavaDoc in all its fully commented and correctly documented glory!

74

Annual Audits Managed Bean JavaDoc Generation

75

Recommended Resources

76

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!

http://stackoverflow.com/

http://www.coderanch.com/forums/f-82/JSF

http://notesin9.com/

Related Sessions

77

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

Thank You For Coming!

78

Q & A

Questions?

¿Preguntas?

Domande?

Haben Sie Fragen?

有问题吗？

Spørsmål?

Spørgsmål?

質問はありますか？

79


Legal disclaimer © IBM Corporation 2013. All Rights Reserved. The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is

provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

JMP402 Master Class: Managed beans and XPages: Your Time Is Now

Documents

Transcript of JMP402 Master Class: Managed beans and XPages: Your Time Is Now