17 Using VarPacks (Variable Packages)

A Variable Package (VarPack) is essentially a set of name-value pairs stored on the application. VarPacks are mainly used to store the values from an xml file (e.g., PT_HOME\settings\portal\j_config.xml, n_config.xml, or device.xml) in memory so the data can be used easily without directly accessing the xml file.

Oracle WebCenter Interaction ships with a variety of VarPacks that are used throughout the portal. These are loaded into the portal through the PT_HOME\settings\portal\VarPacks.xml file. For an example, see PTConfigVarPack (com.plumtree.portaluiinfrastructure.application.varpacks).

As with Models, Views, and Controls, VarPacks can be deployed using Dynamic Discovery, which allows the framework to be completely extensible. All you need to do is extend the XMLBaseVarPack or BaseVarPack class, as shown in this chapter. Custom VarPacks can be used in PEIs or custom Views, among other things, to simplify the details of accessing an xml data file.

This chapter provides examples and instructions on how to use a custom VarPack, and include step-by-step instructions and sample code for creating and implementing a new Hello World VarPack.

Example VarPack Uses

Two common places to use the VarPack would be a custom View (or Control) or a PEI. For example, a custom VarPack could provide table cell width sizes. The code snippet below shows how to retrieve a value from the VarPack.

Java:

HelloWorldVarPack varPack;
varPack = (HelloWorldVarPack) 
  m_asOwner.GetVarPack(HelloWorldVarPack.VARPACK_ID); 
String strWidth=varPack.GetValueAsString("HelloWorldData","HelloWorldCellWidth"); 
myCell.SetWidth(strWidth);

C#:

HelloWorldVarPack varPack; 
varPack = (HelloWorldVarPack) 
   m_asOwner.GetVarPack(HelloWorldVarPack.VARPACK_ID); 
StringstrWidth = varPack.GetValueAsString("HelloWorldData","HelloWorldCellWidth"); 
myCell.SetWidth(strWidth); 

A custom VarPack could also be used in an ILoginActions PEI to do custom processing based on the current administrative folder. For example, you could do something like the code shown below.

Java:

IPTSessionptSession = (IPTSession) _oUserSession;
IApplicationapp = appData.GetApplication();  
XMLBaseVarPack varPack; 
varPack = app.GetVarPackManager().GetVariablePackage(HelloWorldVarPack.VARPACK_ID);  
intnFolderID = varPack.GetValueAsInt("HelloWorldData","HelloWorldFolderID");  
if (ptSession.GetSessionInfo().GetCurrentUserAdminFolderID() == nFolderID) 
{ 
   // Custom login code. 
} 

C#:

IPTSession ptSession = (IPTSession) _oUserSession;   
IApplication app = appData.GetApplication();   
XMLBaseVarPack varPack; 
varPack = app.GetVarPackManager().GetVariablePackage(HelloWorldVarPack.VARPACK_ID); 
int nFolderID = varPack.GetValueAsInt("HelloWorldData", "HelloWorldFolderID"); 
if (ptSession.GetSessionInfo().GetCurrentUserAdminFolderID() == nFolderID) 
{ 
   // Custom login code. 
} 

Implementing a VarPack

To create a custom VarPack, create a class that extends XMLBaseVarPack or BaseVarPack. XMLBaseVarPack handles the reading of xml files for you. For more detailed information, see the portal API Documentation.

1. Create a custom project and custom VarPack class (for example, a CustomVarPack project and a CustomVarPack class in com.yourcompany.application.varpacks that extends XMLBaseVarPack).

2. Edit the new class in your custom project as needed.

3. Compile the new class into a new JAR/DLL file with an intuitive name. All VarPack file names should follow the standard naming convention and end with "VarPack" (e.g., CustomLoginVarPack).

Note: XMLBaseVarPackonly reads in xml files that are two levels deep with the data in the value attribute of the lowest tag (<root><section><sub-section value="data">). It can be customized to read other formats, as explained below.

Example: Hello World VarPack

In this example, the HelloWorldVarPack class extends XMLBaseVarPackand reads in the contents of the helloworld.xml file and stores them on the application. As noted above, the name of the file is important; it ends with "VarPack".

1. The GetVarPackID() method provides the name that will be used to store this VarPack on the application. The method returns a public static variable containing the name of the VarPack. The VARPACK_ID variable is is used to get the name of the VarPack so it can be retrieved from the application.

   Java:

   /** The string ID of this variable package. */ 
   public static final String VARPACK_ID = "HelloWorldVarPack";  
   public String GetVarPackID() 
   { 
      return VARPACK_ID; 
   } 
   

   C#:

   /// <summary> 
   /// The string ID of this variable package. 
   /// </summary> 
   public const String VARPACK_ID = "HelloWorldVarPack"; 
   public override String GetVarPackID() 
   { 
      return VARPACK_ID; 
   } 
   

2. The GetVarPackXMLFileName() method provides the name of the xml file to be read and stored in this VarPack.

   Java:

   public String GetVarPackXMLFileName() 
   { 
      // The name of the file to read into the VarPack. 
      return "helloworld.xml"; 
   } 
   

   C#:

   public override String GetVarPackXMLFileName() 
   { 
      // The name of the file to read into the VarPack. 
      return "helloworld.xml"; 
   } 
   

3. As noted above, XMLBaseVarPack only supports the specific xml format <root><section><sub-section value="data">. To use xml files formatted in other ways, override the LoadSettingsIntoXPHashtable() method.

Once you have written the code for your new VarPack, you must deploy it for use by the portal, described next.

Deploying a Custom VarPack

After you create a custom project as explained in the previous section, you must deploy it to the portal using Dynamic Discovery. For detailed information and instructions, see Chapter 18, "Deploying Custom Code Using Dynamic Discovery". To deploy a VarPack, use Jar or DLL-Based Dynamic Discovery.

The example below deploys the Hello World VarPack sample code from the previous section. Once you have deployed your code, confirm that it was deployed correctly as explained in Viewing Your Customization in the Portal.

These instructions use Visual Studio in .NET and Ant scripts in Java to deploy your custom code.

First, add the library containing the new HelloWorld VarPack class to the CustomVarPacks.xml file so it can be deployed by Dynamic Discovery as explained below.

1. Navigate to PT_HOME\settings\portal and open CustomVarPacks.xml in a text editor.

2. Add the name of your new VarPack (e.g., HelloWorldVarPack) to the existing XML as shown below. Make sure that the spelling and capitalization is exactly the same as the full class name.

   <root> 
     <interface name="IVarPack"/>
     <interfaceassembly name="httpmemorymanagement"/>
     <class name="com.plumtree.sampleui.application.varpacks.HelloWorldVarPack"/> 
   </root>
   

3. Create the new XML file that will be read by HelloWorldVarPack: open a text editor and create a new file named helloworld.xml and save it in PT_HOME\settings\portal.

4. Add the xml describing the data as shown below and save the file.

   <?xml version="1.0"?>
   <HelloWorldConfig>
     <HelloWorldData>
       <Hello value="World"/>
       <HelloWorld value="Hello World!"/>
       <HelloWorldCellWidth value="50"/>
       <HelloWorldFolderID value="1"/>
     </HelloWorldData>
   </HelloWorldConfig>
   

Once you have created the required files, you must run a clean build to deploy the custom code, as explained below.

Java:

1. Open a command prompt and change the directory to the \ptwebui directory where you installed the portal source code.

2. Run a clean build using the following Ant script: ant build.

3. Generate a new WAR file for the application server using the following Ant script: ant install.

   Note: This target deletes and rebuilds all jar files associated with all the UI source projects (as well as the custom projects in the ptwebui folder).

C#:

1. Build the project in Visual Studio.

2. Visual Studio should copy the samplevarpack.dll file from SOURCE_HOME\samplevarpack\dotnet\prod\bin to PORTAL_HOME\webapp\portal\bin for you. If there are problems with Dynamic Discovery on startup, you might need to do this step manually. This is necessary to allow Dynamic Discovery to find the new library.

Viewing Your Customization in the Portal

Once you have deployed your code, view the changes in the portal to confirm that they were loaded correctly. Use Logging Spy to catch any obvious errors.

1. Open Logging Spy. For details , see the Administrator Guide for Oracle WebCenter Interaction.

2. Click the Set Filters button to open the Filter Settings dialog. Make sure the Debug checkbox is selected. (You will not be able to see the customization run if this logging level is not enabled.)

3. Start the portal and view Logging Spy. During startup, Logging Spy should display a message regarding loading Custom VarPacks. Earlier in the startup process, standard VarPacks are loaded from VarPacks.xml. Be careful not to get these two confused. If no Custom VarPacks were loaded, check the spelling and capitalization of HelloWorldVarPack in the CustomVarPacks.xml file.

4. Open a new browser window and navigate to the portal. Log in as Administrator.

5. Append the following argument to the end of the portal URL: ?space=MemoryDebug and browse to your portal.

6. Scroll down to the Variable Packages section; you should see the HelloWorldVarPack listed.

7. Click the View button next to HelloWorldVarPack to view the data stored in the VarPack.

If you were unable to view the HelloWorldVarPack, see the next section for debugging instructions.

Debugging and Troubleshooting

This page provides technical tips for common problems and instructions on how to debug your new VarPack.

Technical Tips

If your custom VarPack is not loaded correctly, first check the following items:

• Be careful to list the full class name of the HelloWorldVarPack class in CustomVarPacks.xml exactly as it is spelled in the code. It will not load if spelled or capitalized incorrectly. This might not produce errors during startup. One way to check that the VarPack is loaded correctly is to make sure that Logging Spy says the correct number was loaded (i.e., 1).

• Make sure that the name of the xml data file (HelloWorld.xml) is the same as the file name returned by the GetVarPackXMLFileName() method, and that the xml data file is located in the PT_HOME\settings\portal directory.

• Check the syntax of the xml data in HelloWorld.xml. If there are syntax errors or the file is formatted incorrectly, it will not load. The XMLBaseVarPack class can only read in xml files that have a single root node with multiple section nodes underneath it. The section nodes contain multiple name/value pair nodes where the name of the node is the name and the value attribute is the value (i.e. <NodeName value="NodeValue"/>). If you need to use a different format, you must override the LoadSettingsIntoXPHashtable() method.

If none of these tips solve the problem, debug your code using the instructions below.

Debugging

These instructions use the HelloWorldVarPack class created on the previous pages as an example.

Java:

1. In Eclipse, stop the Tomcat debugging session and open HelloWorldVarPack.java.

2. Add a breakpoint at the return "helloworld.xml"line.

3. In the Eclipse menu, click Run | Debug… and select the Tomcat application.

4. Choose the Classpath tab, select Add Projects, and add the samplevarpack project.

5. Hit Debug (and Save to retain your changes).

6. Start the portal.

7. You should hit this breakpoint once during startup, when the XMLBaseVarPack class asks the HelloWorldVarPack which xml file to load.

C#:

1. Stop the Visual Studio debugger (and close your browser if it is still open) and open HelloWorldVarPack.cs in Visual Studio.

2. Add a breakpoint as shown below.

3. Start the Visual Studio debugger (F5 or Start | Debug) and wait for the portal to start up.

4. You should hit this breakpoint once during startup, when the XMLBaseVarPack class asks the HelloWorldVarPack which xml file to load.