com.novell.emframe.dev
Class PropertyBookPage

java.lang.Object
  com.novell.emframe.dev.Plugin
      com.novell.emframe.dev.PropertyBookPage

Direct Known Subclasses:

DirPropertyBookPage

public abstract class PropertyBookPage

extends Plugin

Base class used to create property book pages that edits an eDirectory object. Most PropertyBookPages will want to extend DirPropertyBookPage instead of just PropertyBookPage to take advantage of eDirectory Access Service features.

A PropertyBookPage consists of Business Logic, Presentation Logic, and a Plug-in Descriptor:

Business Logic

• Contained in Java files.
• Communicates with iManager through the PropertyBookPage class.
• Communicates with eDirectory using the AdminNamespace acquired from the AuthenticationBroker. PropertyBookPages can also make their own connection to any back end resource, and the PropertyBookPage is responsible for cleaning up any connections made. Current iManager credentials can also be obtained through the AuthenticationBroker to assist in single sign-on. The AuthenticationBroker can be obtained from the PropertyPageContext object (which extends the PluginContext object) passed into many methods using context.getAuthenticationBroker().
• Can put attributes on the HttpServletRequest for use by the Presentation Logic. Use context.getRequest() to obtain the HttpServletRequest.
• See the "Helper Classes" below for more class that can help you write your PropertyBookPage.

Presentation Logic

• Contained in JSP files in webapps/nps/portal/modules/(moduleid)/skins/default/devices/(device type).
• Can read attributes from the HttpServletRequest given by the Business Logic.
• Current valid device types are: "browser" meaning Internet Explorer, "mozilla" meaning Mozilla based browsers like Netscape, Mozilla, and Firefox, "default" meaning all other browsers, and "pocket" meaning pda devices like Palm, Windows CE, etc....
• Generally, if you are not doing device specific functionality like drag and drop or heavy use of browser specific JavaScript in your JSP files, you can put all of your JSP files in the "default" device directory. iManager looks on a file by file basis for a specific JSP file, meaning you can have 100 generic JSP files in the "default" directory, and two Internet Explorer specific JSP files in the "browser" directory. iManager will look first for a device specific JSP file and then in the "default" directory for a generic JSP.
• See the iMan Tag Library Reference and iMan Tag Library Demo on the "Developer" view of iManager for more information on helper tags you can use in your JSP files.

Plug-in Descriptor

• Contained in XML files in webapps/nps/portal/modules/(moduleid)/install or webapps/nps/portal/modules/(moduleid)/plugins. PropertyBookPages should generally be registered in the plugins directory. Plugins that do not appear as selectable Tasks down the left side (there are many types of plug-ins like PropertyBookPages, creators, deletors, etc...) should be registered in the plugins directory.
• Registers Modules, Roles, Tasks, PropertyBookPages, etc... with iManager.
• An XML plug-in descriptor can contain multiple Roles, Tasks, and PropertyBookPages in the same file (the file name does not matter).
• You should pick a unique id for your module (called the moduleid) as a short but unique name representing your product. For example, GroupWise could use GW as its moduleid. Use the moduleid to help guarantee uniqueness throughout iManager, such as in the file system under webapps/nps/portal/modules/(moduleid) directory where you store module specific files, in the ID of your PropertyBookPages (ex. <id>moduleid.MyPropertyBook<id>), and when you get and put settings on the session cache using context.setAttribute( "moduleid.mysetting", "settingvalue" ).
• See the iManager XML Schema for Plug-ins under the page element for more information on constructing your plug-in descriptor.

All elements of a PropertyBookPage are zipped up in a module file with a .npm extension. See the iManager 2.x Developer Kit for more information on writing PropertyBookPages, the iManager file structure of where to put the different elements of the PropertyBookPage, and how to build .npm files.

Do NOT hardcode the "nps" name in any paths to files in JSPs or referenced by your business logic. The web application name "nps" may change in the future, and you can use the PluginContext method context.getModulesPath() to return the path in your JSP file to the webapps/nps/portal/modules directory.

Helper classes

The PropertyPageContext and TaskContext objects are based upon PluginContext. The PluginContext given in many methods allows you access to all information needed for your PropertyBookPage. See PluginContext for details as to the objects you can access.

There are several static classes that may be of help to you. See the eMFrameUtils and DirUtils classes for more information. Some of the DirUtils methods require an instantiated DirUtils object. You can obtain an instantiated DirUtils object from the PluginContext passed into many methods using context.getDirUtils().

Debug logging is available through static methods on the D class. Debug output always shows up on STDERR, but can be configured to go to the STDOUT and to a file with various debugging levels.

Order of methods called on your PropertyBookPage:

• shouldRun(javax.servlet.http.HttpServletRequest, java.lang.String) - Before your class is instantiated, this method is called to see if iManager should instantiate your PropertyBookPage and display it for selection by the user. If you have special considerations to check before your PropertyBookPage is shown (such as your PropertyBookPage will only work on a particular operating system, if you require schema extentions to be performed, etc...), overwrite the shouldRun call and do any checking. Make sure to call the parent shouldRun method as well.
• init(com.novell.emframe.dev.PluginContext, org.jdom.Document) - When your class is instantiated, this method is called to perform any initialization. Your PropertyBookPage will be instantiated when the PropertyBook containing your PropertyBookPage is instantiated.
• RuntimePlugin.shouldShow - If you have extended the RuntimePlugin interface, this method is called when your PropertyBookPage should be shown but allows you to check the selected object for information before showing your PropertyBookPage.
• show(com.novell.emframe.dev.PropertyPageContext) - This method is called when your PropertyBookPage is first selected.
• cache(com.novell.emframe.dev.PropertyPageContext) - This method is called when another PropertyBookPage is selected and you should cache any data.
• canCommit(com.novell.emframe.dev.TaskContext, java.util.Properties) - This method is called when the user presses OK or Apply. Your PropertyBookPage is given the chance to look at the data and veto the save.
• commit(com.novell.emframe.dev.PropertyPageContext) - This method is called when your PropertyBookPage should save any changes made.
• release() - This method is called when your PropertyBookPage's lifecycle is complete. Overwrite this method if you need to perform any cleanup before your PropertyBookPage is released.

Objects based on classes derived from DirPropertyBookPage can either be added to a PropertyBook object or run independently. If run independently, eMFrame will create a PropertyBook object displaying only the DirPropertyBookPage object.

Field Summary

protected Chapter	m_chapter Chapter that contains this page.
protected java.lang.String	m_displayName Localized display name of the page.
protected java.lang.String[]	m_handledAttributeNames Attributes this page handles.
protected java.lang.String	m_helpfile Helpfile of the page.
protected java.lang.String	m_id Unique ID of the page.
boolean	m_IsDirty Has information changed on this page (dirty).
boolean	m_isXML Is this page XML.
protected java.util.Properties	m_JSPDataObject Deprecated. Use request.setAttribute(String, Object) instead
protected org.jdom.Document	m_pageDoc XML Document describing the page.
protected java.util.Properties	m_parameters Properties of this page.
PropertyBook	m_propertyBook PropertyBook that contains this page.
protected java.lang.String	m_template Template of the page.

Constructor Summary

PropertyBookPage()

Method Summary

void	apply(TaskContext context, java.util.Properties resultStrings) Deprecated. Use commit(PropertyPageContext context) instead
void	cache(PropertyPageContext context) The cache method is called when another PropertyBookPage has been chosen.
void	canCommit(PropertyPageContext context) This method is called when the user clicks the "OK" or "Apply" buttons.
void	canCommit(TaskContext context, java.util.Properties resultStrings) Deprecated. Use canCommit(PropertyPageContext context) instead
void	commit(PropertyPageContext context) This method is to COMMIT the changes to the data source.
Chapter	getChapter() Gets the chapter (tab).
java.lang.String[]	getHandledAttributeNames() Returns a String[] of all attributes that this page is going to take care of.
java.lang.String	getHelpFilename() Should return the filename as a string in the form moduleName.fileName (ex base.userHelpFile).
java.lang.String	getId() Get the unique ID of this page.
java.lang.String	getName(TaskContext context) Gets the page's localized display name.
java.lang.String	getTemplate() Gets the merge template (.jsp).
void	init(PluginContext context, org.jdom.Document doc) Initializes the member variables with data from an XML configuration document.
void	release() Called by iManager when the PropertyBookPage has been released and should be collected in the future.
void	save(TaskContext context, java.util.Properties resultStrings) Deprecated. Use cache(PropertyPageContext context) instead
void	setChapter(Chapter chapter) The chapter is the tab which the page shows up on.
static void	shouldRun(javax.servlet.http.HttpServletRequest req, java.lang.String sServiceName) Returns whether this PropertyBookPage should be able to run.
void	show(PropertyPageContext context) The show method is called when a PropertyBookPage is first selected.
void	show(TaskContext context, java.util.Properties resultStrings) Deprecated. Use show(PropertyPageContext context) instead

Methods inherited from class com.novell.emframe.dev.Plugin

isPluginAvailable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

m_chapter

protected Chapter m_chapter

Chapter that contains this page.

m_displayName

protected java.lang.String m_displayName

Localized display name of the page.

m_handledAttributeNames

protected java.lang.String[] m_handledAttributeNames

Attributes this page handles.

m_helpfile

protected java.lang.String m_helpfile

Helpfile of the page.

m_id

protected java.lang.String m_id

Unique ID of the page.

m_IsDirty

public boolean m_IsDirty

Has information changed on this page (dirty).

m_isXML

public boolean m_isXML

Is this page XML.

m_JSPDataObject

protected java.util.Properties m_JSPDataObject

Deprecated. Use request.setAttribute(String, Object) instead

Properties to pass to the JSP.

m_pageDoc

protected org.jdom.Document m_pageDoc

XML Document describing the page.

m_parameters

protected java.util.Properties m_parameters

Properties of this page.

m_propertyBook

public PropertyBook m_propertyBook

PropertyBook that contains this page.

m_template

protected java.lang.String m_template

Template of the page.

Constructor Detail

PropertyBookPage

public PropertyBookPage()

Method Detail

apply

public void apply(TaskContext context,
                  java.util.Properties resultStrings)
           throws PageException

Deprecated. Use commit(PropertyPageContext context) instead

This method is to COMMIT the changes to the data source. If you are working with an NSObject in your save method you most likely will not need to override this method. Some reasons to override this method are to update back links and to write changes to the datasource through an API other than the NDSNamespace. This method is only called for dirty pages (those that have been seen by the user).

Parameters:

context - TaskContext of the plug-in

resultStrings - Properties object to be added to the request

Throws:

PageException

See Also:

commit(com.novell.emframe.dev.PropertyPageContext)

cache

public void cache(PropertyPageContext context)
           throws PageException

The cache method is called when another PropertyBookPage has been chosen. For example, if page A is visible, and the user chooses to jump to page B, page A's cache method is called before page B's show method is loaded.

The primary goal of this method should be to cache the data posted from the client in some in-memory object. For those writing to eDirectory this should most often be by saving the data to an NSObject. You can get a reference to the NSObject by calling getDirPropertyBook().getNSObject(). You should never call nsobj.update(). This will be called by the framework when the "OK" of "Apply" button is pressed.

Parameters:

context - PropertyPageContext based upon the TaskContext and the PropertyBookPage

Throws:

PageException

canCommit

public void canCommit(PropertyPageContext context)
               throws PageException

This method is called when the user clicks the "OK" or "Apply" buttons. It is called for all pages of a book whether the page was shown or not. The method is called after the currentPage.save(...) but before the NSObject update method is called (which is before the page apply method is called). If a PageException is thrown, the nsobj.update will not be called and non of the page.apply methods will be called. A message will be shown to the user.

Parameters:

context - PropertyPageContext based upon the TaskContext and the PropertyBookPage

Throws:

PageException

canCommit

public void canCommit(TaskContext context,
                      java.util.Properties resultStrings)
               throws PageException

Deprecated. Use canCommit(PropertyPageContext context) instead

This method is called when the user clicks the "OK" or "Apply" buttons. It is called for all pages of a book whether the page was shown or not. The method is called after the currentPage.save(...) but before the NSObject update method is called (which is before the page apply method is called). If a PageException is thrown, the nsobj.update will not be called and non of the page.apply methods will be called. A message will be shown to the user.

Parameters:

context - TaskContext of the plug-in

resultStrings - Properties object to be added to the request

Throws:

PageException

See Also:

canCommit(com.novell.emframe.dev.TaskContext, java.util.Properties)

commit

public void commit(PropertyPageContext context)
            throws PageException

This method is to COMMIT the changes to the data source. If you are working with an NSObject in your save method you most likely will not need to override this method. Some reasons to override this method are to update back links and to write changes to the datasource through an API other than the NDSNamespace. This method is only called for dirty pages (those that have been seen by the user).

Parameters:

context - PropertyPageContext based upon the TaskContext and the PropertyBookPage

Throws:

PageException

getChapter

public Chapter getChapter()

Gets the chapter (tab).

Returns:

Chapter containing this page

See Also:

setChapter(com.novell.emframe.dev.Chapter)

getHandledAttributeNames

public java.lang.String[] getHandledAttributeNames()

Returns a String[] of all attributes that this page is going to take care of.

Returns:

Array of strings of attribute names.

getHelpFilename

public java.lang.String getHelpFilename()

Should return the filename as a string in the form moduleName.fileName (ex base.userHelpFile).

Returns:

String containing the help filename

getId

public java.lang.String getId()

Get the unique ID of this page.

Returns:

String containing the pageId (comes from the xml description)

getName

public java.lang.String getName(TaskContext context)

Gets the page's localized display name.

Parameters:

context - TaskContext of the plug-in

Returns:

String containing the localized display name

getTemplate

public java.lang.String getTemplate()

Gets the merge template (.jsp).

Returns:

String containing the merge template

init

public void init(PluginContext context,
                 org.jdom.Document doc)

Initializes the member variables with data from an XML configuration document.

Overrides:

init in class Plugin

Parameters:

context - PluginContext of the plug-in

doc - XML Document registering this page

release

public void release()

Called by iManager when the PropertyBookPage has been released and should be collected in the future. Overwrite this method if you need to perform cleanup when your PropertyBookPage is released for garbage collection by iManager. Any connections initialized directly by this PropertyBookPage should be cleaned up. Make sure to call the parent release() method so the system can do any cleanup it needs.

save

public void save(TaskContext context,
                 java.util.Properties resultStrings)
          throws PageException

Deprecated. Use cache(PropertyPageContext context) instead

The primary goal of this method should be to cache the data posted from the client in some in-memory object. For those writing to eDirectory this should most often be by saving the data to an NSObject. You can get a reference to the NSObject by calling getDirPropertyBook().getNSObject(). You should never call nsobj.update(). This will be called by the framework when the "OK" of "Apply" button is pressed.

Parameters:

context - TaskContext of the plug-in

resultStrings - Properties object to be added to the request

Throws:

PageException

See Also:

cache(com.novell.emframe.dev.PropertyPageContext)

setChapter

public void setChapter(Chapter chapter)

The chapter is the tab which the page shows up on.

Parameters:

chapter - Chapter object to contain this page

See Also:

getChapter()

shouldRun

public static void shouldRun(javax.servlet.http.HttpServletRequest req,
                             java.lang.String sServiceName)
                      throws java.lang.Exception

Returns whether this PropertyBookPage should be able to run.

Parameters:

req - HttpServletRequest

sServiceName - String containing the id of this PropertyBookPage

Throws:

java.lang.Exception - if this PropertyBookPage cannot run

show

public void show(PropertyPageContext context)
          throws PageException

The show method is called when a PropertyBookPage is first selected. Read data from cached data-source and stuff results on the HttpServletRequest to be rendered by the JSP.

Parameters:

context - PropertyPageContext based upon the TaskContext and the PropertyBookPage

Throws:

PageException

show

public void show(TaskContext context,
                 java.util.Properties resultStrings)
          throws PageException

Deprecated. Use show(PropertyPageContext context) instead

Read data from cached data-source. Stuff results in xml/properties to be rendered.

Parameters:

context - TaskContext of the plug-in

resultStrings - Properties object to be added to the request

Throws:

PageException

See Also:

show(com.novell.emframe.dev.PropertyPageContext)