com.objectplanet.survey.plugin
Class Plugin

java.lang.Object
  com.objectplanet.survey.plugin.Plugin

Direct Known Subclasses:

Plugin.Broken

public abstract class Plugin
extends java.lang.Object

Plugin is an abstract class that all plugins must implement. The methods required is interface between the system and a plugin.

Author:

Torgeir Punnerud

Created:

26. august 2002

Nested Class Summary

static class	Plugin.Broken A placeholder for a plugin that didn't load.
static class	Plugin.JAR A JAR file.

Field Summary

static java.lang.String

DEFAULT_SETUP_HTML Deprecated. Will be made private when getSetupHTML() is removed

Constructor Summary

Plugin()

Method Summary

java.lang.String	getClassName() Returns the plugin's class name.
java.lang.String	getErrorMsg() Deprecated. from version 6.0 The ProcessResult object is used instead of error message.
boolean	getFailedToLoad() Return true if plugin failed to load
int	getFunctionCount() Gets the number of functions provided by the plugin.
java.lang.String	getFunctionHTML(int functionNo, java.util.HashMap resources) Gets the HTML code for plugin function.
java.lang.String	getFunctionIconBig(int functionNo, java.util.HashMap resources) Gets page icon for the plugin function.
java.lang.String	getFunctionIconSmall(int functionNo, java.util.HashMap resources) Gets icon for the plugin function menu item.
java.lang.String	getFunctionLabel(int functionNo, java.util.HashMap resources) Gets the link label to the plugin function.
java.lang.String	getFunctionUrl(int functionNo, java.util.HashMap resources) Url to go to when link with label getFunctionLabel(int functionNo, HashMap resources) is clicked.
java.lang.String	getHelpHTML() NOTE: this method is not yet used by Opinio. Gets the HTML code for displaying help.
java.lang.String	getHelpURL() Gets the help url for linking the plugin's help page to the plugin setup screen and the pluginMenuHook.jsp.
Plugin.JAR	getJAR() Returns the JAR file containing this plugin.
java.lang.String	getProperty(java.lang.String propertyName) Method for getting a plugin property value that is stored in the database.
java.lang.String	getSetupHTML() Deprecated. from version 6.0 Use getSetupHTML(HashMap resources) NOTE that <form> element and pluginName hidden field must be removed.
java.lang.String	getSetupHTML(java.util.HashMap resources) Gets the HTML code for plugin setup screen.
boolean	hasFunctionAccess(long userId, int functionNo, java.util.HashMap resources) Checks if user with userId has access to the plugin function number functionNo.
boolean	isMultipartFunctionData(int functionNo, java.util.HashMap resources) Should function be processed as "multipart/form-data"? Overwrite and return true for functions that need form content type "multipart/form-data".
ProcessResult	processFunctionHTML(int functionNo, java.util.HashMap resources) Method for processing the plugin function html.
java.lang.String	processSetup(java.util.Map values) Deprecated. from version 6.0 Use processSetupHTML(HashMap resources)
ProcessResult	processSetupHTML(java.util.HashMap resources) Method for processing the plugin setup html.
void	removeProperty(java.lang.String propertyName) Method for removing a plugin property value in the database.
void	setErrorMsg(java.lang.String errorMsg) Deprecated. from version 6.0 The ProcessResult object is used instead of error message.
void	setProperty(java.lang.String propertyName, java.lang.String propertyValue) Method for saving a plugin property value in the database.
void	start() Any PluginBus registrations should be done here.
void	stop() Method called by the system before exiting.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SETUP_HTML

public static final java.lang.String DEFAULT_SETUP_HTML

Deprecated. Will be made private when getSetupHTML() is removed

Default html for setup screen.

See Also:

Constant Field Values

Constructor Detail

Plugin

public Plugin()

Method Detail

getClassName

public java.lang.String getClassName()

Returns the plugin's class name.

Returns:

The className value

getFailedToLoad

public final boolean getFailedToLoad()

Return true if plugin failed to load

Parameters:

value -

getJAR

public Plugin.JAR getJAR()

Returns the JAR file containing this plugin.

Returns:

The JAR object, representing a jar file

setErrorMsg

public final void setErrorMsg(java.lang.String errorMsg)

Deprecated. from version 6.0 The ProcessResult object is used instead of error message.

Sets the error message. If this is set, configuration of the plugin was unsuccessful, and displayed to the user.

Parameters:

errorMsg - The error message

getErrorMsg

public final java.lang.String getErrorMsg()

Deprecated. from version 6.0 The ProcessResult object is used instead of error message.

Sets the error message

Returns:

The error message

getSetupHTML

public java.lang.String getSetupHTML()

Deprecated. from version 6.0 Use getSetupHTML(HashMap resources) NOTE that <form> element and pluginName hidden field must be removed.

Gets the HTML code needed to perform setup/config operations on this plugin. It is entirely up to the plugin how this setup screen is built. It is recommended that the look & feel of Opinio is used.

The setup must be done with an HTML form. All the form elements/values will be captured by the system on submit, and returned in an map to the plugin through the processSetup() method.

This method is not required by the plugin. If not implemented, a standard no-op text is returned.

Returns:

The HTML code for setup of this plugin.

getFunctionHTML

public java.lang.String getFunctionHTML(int functionNo,
                                        java.util.HashMap resources)

Gets the HTML code for plugin function. The code must include all HTML needed between the form tags. For example, the code could be:

 String html = "Name: <input type=text name=plugin_name length=10><br>" + "Address:
 <input type=password name=plugin_address length=10>" + "<input type=submit value="save"
 name=plugin_savebutton>"; return html;

 

As can be seen from this example code, all input field names must start with "plugin". This is to avoid any conflicts with any fields produced by Opinio. The example includes two fields: "plugin_name" and "plugin_address". When the user enters the values and clicks the button (must also be provided in the code), Opinio will receive the form and return it through a call to the processFunctionHTML(int functionNo, HashMap resources) method. It is then up to the plugin to process the html.

This method is not required by the plugin. If not implemented, a standard no-op text is returned. It is recommended that the look & feel of Opinio is used. IMPORTANT: Plugin is self responsable for survey/folder permission checks. by implemening method hasFunctionAccess() If you need to upload files to you funtions note the following:

• File element name MUST use reserved names - PluginConstants.PARAM_UPLOAD_FILE_NAME_1, PluginConstants.PARAM_UPLOAD_FILE_NAME_2, ..
• Method isMultipartFunctionData(int, HashMap) for the funciton MUST return true
• Uploaded files can be retrieved in processFunctionHTML(int, HashMap) - see method comments

Parameters:

functionNo - Number of the plugin function Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
 HttpResponse   response        = (HttpResponse) resources.get("HttpResponse");
 

Returns:

The HTML code for plugin function number functionNo

getFunctionCount

public int getFunctionCount()

Gets the number of functions provided by the plugin. Default is 1.

Returns:

The number of functions (default 1)

getFunctionUrl

public java.lang.String getFunctionUrl(int functionNo,
                                       java.util.HashMap resources)

Url to go to when link with label getFunctionLabel(int functionNo, HashMap resources) is clicked. This is an url to the plugin function implementation and will be available from page actions box (from Opinio 6.0). Default implementation returns url to Opinio action which checks user login and permissions and displays plugin action html returned by getFunctionHTML(int functionNo, HashMap resources).

Parameters:

functionNo - Number of the function for this url, will be added to the link. Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Then these objects should contain the values needed to produce the url link. In most cases, no values are needed at all, but you may want to send some parameters to the plugin.

Returns:

url to action screen (url to go to when link with label is clicked)

hasFunctionAccess

public boolean hasFunctionAccess(long userId,
                                 int functionNo,
                                 java.util.HashMap resources)

Checks if user with userId has access to the plugin function number functionNo. If user doens't have access: - the function link will not be displayed. - getFunctionHTML() method never be called (even if user tries to manipulate url) - processFunctionHTML() will never be called (even if user tries to manipulate url) Default implementation returns true (all functions are available for all users) See UserManager class, hasSurveyPermission() and hasFolderPermission() methods

Parameters:

userId - Id of the currenlty logged user

functionNo - Function number of this plugin Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Then these objects contain values that might be needed to check the function access.

Returns:

true if user has access to the plugin function

getFunctionLabel

public java.lang.String getFunctionLabel(int functionNo,
                                         java.util.HashMap resources)

Gets the link label to the plugin function. Default implementation returns plugin name (property plugin.#className#.name) or class name if plugin name is not found or set in the properties file.

Parameters:

functionNo - Number of the plugin function. Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Returns:

label of plugin action screen link

getFunctionIconSmall

public java.lang.String getFunctionIconSmall(int functionNo,
                                             java.util.HashMap resources)

Gets icon for the plugin function menu item. If returns null, the default icon will be used.

Parameters:

functionNo - Number of the plugin function. Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Returns:

icon url

getFunctionIconBig

public java.lang.String getFunctionIconBig(int functionNo,
                                           java.util.HashMap resources)

Gets page icon for the plugin function. If returns null, the default icon will be used.

Parameters:

functionNo - Number of the plugin function. Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Returns:

icon url

isMultipartFunctionData

public boolean isMultipartFunctionData(int functionNo,
                                       java.util.HashMap resources)

Should function be processed as "multipart/form-data"? Overwrite and return true for functions that need form content type "multipart/form-data". Default implementation returns false.

Parameters:

functionNo - Number of the plugin function. Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get(PluginConstants.RESOURCE_HTTP_REQUEST);
                                                                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get(PluginConstants.RESOURCE_HTTP_RESPONSE);
 

Returns:

label of plugin action screen link

getSetupHTML

public java.lang.String getSetupHTML(java.util.HashMap resources)

Gets the HTML code for plugin setup screen. The code must include all HTML needed between the form tags. For example, the code could be:

 String html = "Name: <input type=text name=plugin_name length=10><br>" + "Address:
 <input type=password name=plugin_address length=10>" + "<input type=submit value=Save
 name=plugin_savebutton>"; return html;

 

As can be seen from this example code, all input field names must start with "plugin". This is to avoid any conflicts with any fields produced by Opinio. The example includes two fields: "plugin_name" and "plugin_address". When the user enters the values and clicks the button (must also be provided in the code), Opinio will receive the form and return it through a call to the processSetupHTML(HashMap resources) method. It is then up to the plugin to process the setup html.

This method is not required by the plugin. If not implemented, a standard no-op text is returned. It is recommended that the look & feel of Opinio is used. IMPORTANT: Only users with administrator permissions have access to the plugin setup screen. If additional check is required, retrieve USER_ID attribute from session and implement permission check in this method.

Parameters:

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

Returns:

The HTML code for plugin function number functionNo

processFunctionHTML

public ProcessResult processFunctionHTML(int functionNo,
                                         java.util.HashMap resources)

Method for processing the plugin function html. This method is called when the plugins form is submitted. It is up to the implementor (developer) of this method to process the values appropriately. IMPORTANT: Plugin is self responsable for survey/folder permission checks. by implemening method hasFunctionAccess()

Parameters:

functionNo - Number of the plugin function Function number is int value between 1 and getFunctionCount() inclusive

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

If you set the function data to be "multipart/form-data" (method isMultipartFunctionData() returns true), and add uploaded files to the html function page, then the uploaded files can be retrieved like this:

 ArrayList uploadFiles = (ArrayList) resources.get(PluginConstants.RESOURCE_UPLOAD_FILES);
 if (uploadFiles != null && uploadFiles.size() > 0) {
        FormFile firstUploadedFile = (FormFile) uploadFiles.get(0);
 }
 

FormFile is struts interface for uploaded files: org.apache.struts.upload.FormFile

Returns:

The result object with message to show to the user. Let the user know what happened with the processing of the form values. If null returned, the plugin function screen will be displayed again. If result of type error is returned, the error message will be displayed over the function html. If result of type confimation is returned, confirmation message will be displayed, based on user preferences.

processSetupHTML

public ProcessResult processSetupHTML(java.util.HashMap resources)

Method for processing the plugin setup html. This method is called when the plugin's setup form is submitted. It is up to the implementor (developer) of this method to process the values appropriately.

IMPORTANT: Only users with administrator permissions have access to the plugin setup screen. If additional check is required, retrieve USER_ID attribute from session and implement permission check in this method.

Parameters:

resources - This HashMap contains both the HttpRequest and HttpResponse objects, if the current survey is web based. In future versions, other types of objects must be retrieved, if other protocols are used - WAP, for example. The HTTP objects must be retrieved this way:

 HttpRequest    request = (HttpRequest) resources.get("HttpRequest");
                                                                                                                                        HttpResponse    response        = (HttpResponse) resources.get("HttpResponse");
 

These objects should contain the values needed to process the plugin function.

Returns:

The result object with message to show to the user. Let the user know what happened with the processing of the form values. If null returned, the plugin list screen will be displayed. If result of type error is returned, the error message will be displayed over the function html. If result of type confimation is returned, confirmation message will be displayed, based on user preferences.

getHelpHTML

public java.lang.String getHelpHTML()

NOTE: this method is not yet used by Opinio.

Gets the HTML code for displaying help. It is not required, but recommended. A plugin without help is most likely useless for everyone except the developer.

Returns:

The help HTML code

getHelpURL

public java.lang.String getHelpURL()

Gets the help url for linking the plugin's help page to the plugin setup screen and the pluginMenuHook.jsp. If the plugin's help page is added somewhere in the /admin/ folder it is enough to return the following path from here. If the help page is located elsewhere you need to return the complete url. The return string could be something like this ""plugin_SurveyMenuItemPlugin/Help.html". It is not required, but very useful. If the plugin doesn't have a help page, this method will return null and a default plugin help will be displayed.

Returns:

The help url

start

public void start()

Any PluginBus registrations should be done here.

stop

public void stop()

Method called by the system before exiting. Usually, nothing needs to be done here. If the plugin holds any resources, release them here.

processSetup

public java.lang.String processSetup(java.util.Map values)

Deprecated. from version 6.0 Use processSetupHTML(HashMap resources)

Method for processing the setup screen. The values from the setup screen is collected by the system and passed to this method in a Map. It is up to the implementor (developer) of this method to process the values appropriately.

Parameters:

values - The values entered by the user in the setup screen.

Returns:

The confirmation message. Let the user know what happened with the processing of the setup values.

setProperty

public void setProperty(java.lang.String propertyName,
                        java.lang.String propertyValue)
                 throws java.lang.Exception

Method for saving a plugin property value in the database. This enables plugins to put properties in the database instead of the properties file.

Parameters:

propertyName - The property name

propertyValue - The property value

Throws:

java.lang.Exception

getProperty

public java.lang.String getProperty(java.lang.String propertyName)
                             throws java.lang.Exception

Method for getting a plugin property value that is stored in the database.

Parameters:

propertyName - The property name

Returns:

propertyValue The property value

Throws:

java.lang.Exception

removeProperty

public void removeProperty(java.lang.String propertyName)
                    throws java.lang.Exception

Method for removing a plugin property value in the database.

Parameters:

propertyName - The property name

Throws:

java.lang.Exception