Developing Java-Based Pagelets

Business Rules

Java can be used to apply business logic to data to create a result set. Pagelet Wizard can then be used to invoke the Java program. Parameters that are required by the Java program can be defined, managed, and passed to the Java program through Pagelet Wizard. These parameters may be derived from user personalization parameters, as well as administrator-defined parameters and system variables.

For example, the Java program may need the user’s ID, the user’s language, and the user’s personalization selection regarding whether to include historical transaction information or just current information. These parameters can be defined in Pagelet Wizard in relation to a Java class. Pagelet Wizard can access the PeopleSoft runtime environment to determine the user’s ID as well as other profile information, such as the user’s language.

See Understanding System Variables Supported as Data Source Parameters.

Pagelet Wizard will also manage the user interface and storage of user personalization data. This topic is discussed in detail in the subsequent User Personalization section. When the Java program is invoked, Pagelet Wizard will handle passing all required parameters to the Java program.

In addition, Java classes delivered with PeopleTools enable you to call PeopleCode from your Java program and access contextual information from the runtime system. If needed, business data can be retrieved, as necessary, through the numerous PeopleCode functions that are accessible from Java.

The result set created by the Java program may be in an HTML format or in an XML format. Pagelet Wizard will accept the output from the Java program and will manage the presentation of the information within the portal. This topic is discussed in the following User Interface section.

User Interface

Pagelet Wizard will manage all aspects of a pagelet’s user interface. No user-interface-related programming for the pagelet is required in the Java program. Pagelet Wizard can accept an HTML- or XML-based result set from a Java program. The HTML from the Java program can be rendered directly. Alternatively, XML can be transformed with XSL to create an appropriate pagelet user interface.

In either case, Pagelet Wizard will manage the XSL and invoke the transformation at runtime. Extensible Stylesheet Language templates are provided with Pagelet Wizard for general use scenarios. Extensible Stylesheet Language development may be required, depending on the specific user interface required for a pagelet.

See Defining Pagelet Wizard XSL Prototypes.

User Personalization

Pagelet Wizard supports the persistence of user personalization selections for a pagelet application and handles all aspects of the user interface that enable users to enter their preferences and selections. Personalization parameters are defined within Pagelet Wizard administration pages. No programming is required, Java or otherwise.

User personalization selections can occur at two levels. From the homepage, users can select which pagelet applications they want to include on their homepage. After they’ve selected a pagelet application and have decided where they want the pagelets to appear on their homepage, they can personalize a particular pagelet application.

Examples of user personalizations at the second level can include scenarios in which a user selects transactions from a particular region or chooses to include transactions using a particular date as opposed to same-day transactions.

The user interface for all of these activities, as well as the storage of the personalization data for persistence, is managed by Pagelet Wizard without any additional programming, Java or otherwise.

Pagelet Wizard supports functionality that enables an end user to select a pagelet application to appear on his or her homepage. When a pagelet application is registered with Pagelet Wizard, a folder, which represents a portal application category, can be selected. When users personalize their homepage by selecting specific pagelet applications that they want to appear on their homepage, the selection is presented within the category (folder) that is defined when they register the pagelet application through Pagelet Wizard.

See Step 6: Specifying Pagelet Publishing Options.

Pagelet Wizard also supports functionality that enables an end user to select values that allow a specific pagelet application to be personalized. The functionality may dictate that some input parameters that are required by a Java program be entered by an end user, while other parameters can be set by an administrator. Pagelet Wizard manages parameter passing and the user interface. Pagelet Wizard inspects the Java source code for input parameters. Pagelet Wizard administrators can then select which parameters can be accessed by an end user for personalization. The user interface to enables an end user to personalize a pagelet application and update the appropriate Java input parameters is automatically generated and managed by Pagelet Wizard.

Navigation

When creating links in your pagelet application that enable a user to navigate to a related page for details and so forth, the link may need to be proxied by the portal to keep the user within the portal. For example, if a pagelet link is not proxied, then the pagelet can take a user to a site that is completely independent from the portal. In this scenario, the navigational links on the portal header, the homepage menu pagelet, and the left-hand menu pagelet will not be available to the user.

If the link is proxied by the portal, then the link can access and display content from a site that is independent of the portal. However, the content will be rendered within the portal. For example, the portal’s header and left-hand menu will be available.

With the PeopleSoft Interaction Hub, links that are included in a pagelet will be altered automatically to support proxying by the portal. No programming is required, Java or otherwise.

Navigation on Extended Pages

Clicking a link on an extended page displays content within the target frame. The PeopleSoft Interaction Hub, header, and left-hand menu area will remain. Therefore, the new content will be rendered in the context of the PeopleSoft Interaction Hub.

The Return to Home link, which returns the user to the portal homepage, may be required from an extended page. The GenerateHomepagePortalURL function creates a URL string that represents an absolute reference to the portal homepage. Because you can access the PeopleSoft runtime environment from a Java program and you can access PeopleCode built-in functions, you can invoke the GenerateHomepagePortalURL function from your Java program.

See Developing Java-Based Pagelets.

See GenerateHomepagePortalURL

Portal Integration

The pagelet application needs to be integrated with the portal registry so that the pagelet application is managed, secured, and presented through the PeopleTools portal. Registration makes the portal aware of a pagelet. Information included in registration determines the name and security for your pagelet application. In addition, registration data determines the category in which the pagelet application resides. Users view pagelet applications within these categories when selecting items that they want to see on their homepage. No programming is required, Java or otherwise, to complete portal registration.

Invoking Java from PeopleCode

Three primary Java PeopleCode functions are used to invoke Java from PeopleCode:

• GetJavaClass

• CreateJavaObject

• CreateJavaArray

result = java.class.name.SomeStaticMethod();

&Result = GetJavaClass("java.class.name").
SomeStaticMethod();

&Sys = GetJavaClass("java.lang.System");
&Sys.setProperty("java.security.policy", "C:\java\policy");
WinMessage("The security property is: " | 
&Sys.getProperty("java.security.policy"));
&Props = &Sys.getProperties();
&Props.put("java.security.policy", "C:\java\policy");
&Sys.setProperties(&Props);
WinMessage("The security property is: " | 
&Sys.getProperty("java.security.policy"));

intArray = new int[]{1, 2, 3, 5, 8, 13};

&IntArray = CreateJavaObject("int[]", 1, 2, 3, 5, 8, 13);

/* Example to return Random Passwords from a Java class */
Local JavaObject &oGpw;
/* Create an instance of the object */
&oGpw = CreateJavaObject("com.PeopleSoft.Random.Gpw_Demo");
&Q = "1";
/* Call the method within the class */
&NEW_VALUE = &oGpw.getNewPassword(&Q, PSRNDMPSWD.LENGTH);
/* This is just returning one value for now */
PSRNDMPSWD.PSWD = &NEW_VALUE;

Local JavaObject &Abc, &RefArray;
Local array of String &Parms;
&Parms = CreateArray();
/* Populate array how ever you want to populate it */
&Abc = GetJavaObject("com.peoplesoft.def.Abc");
/* Create the java array object. */
&JavaParms = CreateJavaArray("java.lang.String[]",  &Parms.Len);
/* Populate the java array from the PeopleCode array. */
&RefArray = GetJavaClass("java.lang.reflect.Array");
For &i = 1 to &Parms.Len
	&RefArray.set(&JavaParms, &i - 1, &Parms[&i]);
End-For;
/* Call the method. */
&Abc.xyz(&JavaParms);

Accessing the PeopleSoft Runtime System from Java

After a Java class has been invoked, the class can access the PeopleSoft runtime system. Java classes delivered with PeopleTools enable you to call PeopleCode from your Java program and access contextual information from the runtime system, such as the current user’s role and language preference. By importing the PeopleTools-delivered Java classes in your Java program, you can have access to PeopleCode objects and methods. Hundreds of PeopleSoft system variables, constants, and built-in functions are available for use with this approach. Discussions of the various methods follow.

Accessing the runtime system works only from a Java program that was initially called from PeopleCode. You must call PeopleCode facilities only from the same thread that was used for the call into Java. You cannot call any PeopleCode facility that would cause the server to return to the browser for an end-user action because the state of the Java computation cannot be saved and restored when the action is complete.

REC_NAME.FIELD_NAME

new PeopleSoft.PeopleCode.Name("REC_NAME", "FIELD_NAME");

Page.PAGE_NAME

new PeopleSoft.PeopleCode.Name("Page", "PAGE_NAME");

/* This code is used to test the Java/PeopleCode interface. */
import PeopleSoft.PeopleCode.*;
public class Test {
/*
* Add up and return the length of all the
* item labels on the UTILITIES menu,
* found two different ways.
*/
public static int Test() {
/* Get a Rowset to hold all the menu item records. */
Rowset rs = Func.CreateRowset(new Name("RECORD", "PSMENUITEM"), new Object[]{});
String menuName = "UTILITIES";
int nRecs = rs.Fill(new Object[]{"WHERE FILL.MENUNAME = :1", menuName});
int i;
int nFillChars = 0;
for (i = 1; i <= rs.getActiveRowCount(); i++) {
String itemLabel = (String)rs.GetRow(i)
.GetRecord(new Name("RECORD", "PSMENUITEM"))
.GetField(new Name("FIELD", "ITEMLABEL"))
.getValue();
nFillChars += itemLabel.length();
}
/* Do this a different way - use the SQL object to read each menu
item record. */
int nSQLChars = 0;
Record menuRec = Func.CreateRecord(new Name("RECORD", "PSMENUITEM"));
SQL menuSQL = Func.CreateSQL("%SelectAll(:1) WHERE MENUNAME = :2",
new Object[]{menuRec, menuName});
while (menuSQL.Fetch(new Object[]{menuRec})) {
String itemLabel = (String)menuRec
.GetField(new Name("FIELD", "ITEMLABEL"))
.getValue();
nSQLChars += itemLabel.length();
}
return nFillChars + 100000 * nSQLChars;
}
}

Local JavaObject &Test;
Local number &chars;
&Test = GetJavaClass("Test");
&chars = &Test.Test();
&Test = Null;
WinMessage("The character counts found are: " | &chars, 0);

Creating the Component Interface

To expose a component to a third party, you must first create a component interface definition. You do this through the PeopleSoft Application Designer. Using drag-and-drop functionality, you can specify the properties and methods of the component that you want to expose. Numerous component interface definitions are delivered with the each PeopleSoft application.

Image: BUSINESS_EXPENSES component interface definition

The BUSINESS_EXPENSES component definition appears in the left frame in the following example. The properties and methods that are exposed through this interface are displayed in the right frame.

The following screenshot displays Bus_Exp component interface definition in the left frame and properties and methods in the right frame.

Image: SDK_BUS_EXP component interface

After the component interface definition is saved, you can then generate the Java classes for invoking this interface. You do this using the Generate Java Template command in PeopleSoft Application Designer:

The following screenshot illustrates an example of invoking the SDK_BUS_EXP component interface and generating Java classes.

See Understanding Component Interface Class.

Invoking the Component Interface from Java

To invoke the Business Expense component interface from Java.

1. Connect to the application server.

   To access a component interface, you need to establish a PeopleSoft session. To create a session object, use the Session.Connect () method. The Connect method, which takes five parameters, actually signs in to a PeopleSoft session. The Connect() method connects a session object to a PeopleSoft application server. Note that various options are available for using an existing connection and disconnecting and switching connections.

   import PeopleSoft.ObjectAdapter.*;
   import PeopleSoft.Generated.PeopleSoft.*;
   import PeopleSoft.Generated.CompIntfc.*;
   private ISession oSession;
   private CAdapter oAdapter;
   oAdapter = new CAdapter();
   oSession = new CSession(oAdapter.getSession());
   oSession.Connect(1,"//EHARRIS032000:9000","PTDMO","PTDMO",new byte[0]);
   

2. Get an instance of the component interface.

   Use the GetComponent() method with a session object to get an instance of a previously created component interface.

   busExpense = new CBusExp( oSession.GetComponent( "BUS_EXP" ));

3. Find an existing record.

   You can query a component interface to find relevant data instances based on primary and alternate search keys.

   busExpense.setName( searchDialogStrings[ 0 ]);
   busExpense.setLastNameSrch( searchDialogStrings[ 1 ]);
   busExpense.setEmplid( searchDialogStrings[ 2 ] );
   return( busExpense.Find() );
   

4. Get an instance of data.

   GetKeys are the key values required to return a unique instance of existing data. GetKeys can be set by means of simple assignment to the properties of the component interface and then the Get() method can be invoked. This populates the component interface with data based on the key values that you set; this has been referred to here as a data instance.

   busExpense.setEmplid( getKey );
   boolean result = busExpense.Get();
   

5. Migrate through collections of data.

   After getting a data instance, get access to the data in the component interface. PeopleSoft organizes component interface data within collections. Rows of data in a collection are called items.

   The following code creates a connection to the application server, gets the component interface, and fetches the first item in a collection.

   oAdapter = new CAdapter();
   oSession = new CSession(oAdapter.getSession());
   oSession.Connect(1,"//EHARRIS032000:9000","PTDMO","PTDMO",new byte[0]);
   busExpense = new CBusExp( oSession.GetComponent( "BUS_EXP" ));
   busExpense.setEmplid( getKey );
   boolean result = busExpense.Get();
   busExpenseFirstScrollItemCollection = busExpense.getBusExpensePer();
   busExpenseFirstScrollItem = firstScrollCollection.Item
   ( firstScrollIndex );
   return( busExpenseFirstScrollItem.getBusExpenseDtl() );
   

6. Edit and access data in an item.

   Editing and accessing component interface data in Java is rather straightforward. The following Java code accesses the various public members of the class.

   long j = busExpenseSecondScrollCollection.getCount();
   Object [][] data = new Object[ ((int)j + 1) ][ 7 ];
   for( int i = 1; i < j + 1 ; i++ )
   {
   busExpenseSecondScrollItem = busExpenseSecondScrollCollection.Item( i );
   data[(i - 1)][0] = busExpenseSecondScrollItem.getBusinessPurpose();
   data[(i - 1)][1] = busExpenseSecondScrollItem.getChargeDt();
   data[(i - 1)][2] = busExpenseSecondScrollItem.getCurrencyCd();
   data[(i - 1)][3] = busExpenseSecondScrollItem.getDeptid();
   data[(i - 1)][4] = busExpenseSecondScrollItem.getExpenseAmt();
   data[(i - 1)][5] = busExpenseSecondScrollItem.GetPropertyByName
   ("ExpenseCd");
   data[(i - 1)][6] = busExpenseSecondScrollItem.GetPropertyByName
   ("CurrencyCd");
   }return( data );
   

   In the following example, data is accessed by means of the getNAME_OF_PRPERTY() method of an item or by means of the generic getPropertyByName() method. This code illustrates the way in which an entire collection of data can be captured and packaged into an object for transfer to a calling object.

   busExpenseFirstScrollItem.setEmplid( emplid );
   busExpenseFirstScrollItem.setExpensePeriodDt( expensePeriodDt );
   return( busExpense.Save() );
   

   Just as before, data is edited by means of item objects and the setNameOfPropery() method of those items. Also note that you needed to call the Save() method on the component interface to commit the changes.

7. Insert an item into a collection and delete an item from a collection.

   Collection objects in Java contain the InsertItem() method in which the return value is the item that has just been inserted. After a new item is created, simply edit data in it and then remember to call the Save() method to commit the changes.

   busExpenseSecondScrollItem = busExpenseSecondScrollCollection.
   InsertItem( secondScrollIndex );

   Similarly, a DeleteItem() method is available:

   busExpenseSecondScrollCollection.DeleteItem( secondScrollIndex );

8. Disconnect from a session.

   After a session is no longer needed, it should be disconnected from the application server. This is done by calling the Disconnect() method on the session object.

   oSession.Disconnect();