com.prosyst.mprm.admin.procedures

Interface Procedure

public interface Procedure

A procedure is characterized with some mandatory and some optional fields. The mandatory ones are name, text and path in the directory tree. Combined, the path and the name form the unique identifier for the procedure. The constraints of these features will be explained in the method descriptions below. The optional features concede extra usability and flexibility via the Administration GUI applications. They can give the opportunity for the user to set an icon, assign a shortcut, and, if a procedure is parameterised, to assign the descriptions and the types of the expected arguments. The optional features of a procedure are not dependent on each other. This means that an icon may be set to a procedure without assigning a shortcut or parameterise the procedure, or giving argument descriptions, and vice versa. The aim of the icon is the customized visualization everywhere the procedure will be shown. It gives the user a chance to use own favourite picture and her procedure to be different from the others. If a procedure is often used the user can assign a shortcut to it. As a consequence of this setting, for example, the procedure will be shown as a button in the Devices node of the mPRM Administration GUI. It is possible to execute the procedure in the easiest way. The specifics of the procedure allow it to be parameterised, and the parameters to be replaced with the actual values just before the execution. There are some methods which deal with the procedure's arguments. A procedure argument is described with a type, a description and a value. The implementation has the aim to save the argument type and descriptions if there are any. The user will enter them when saving the procedure for the Graphical User Interface and will help him in the settings before the actual execution of a procedure.

Method Summary

Modifier and Type	Method and Description
Argument[]	getArguments() Gets the arguments info of the current procedure.
java.io.InputStream	getIcon() Gets the icon that is set for this procedure.
java.lang.String	getName() Gets the name of the procedure object.
java.lang.String	getPath() Gets the path of the procedure object.
java.lang.String	getText() Gets the specified text of the procedure.
boolean	hasIcon() Indicates whether the procedure has set icon or not.
boolean	hasShortcut() Indicates whether this procedure has a shortcut assigned to it.
void	moveTo(java.lang.String targetFolderPath, boolean replace) Move this procedure to the specified folder.
void	setArguments(Argument[] arguments) Sets a list of arguments for this procedure.
void	setIcon(java.io.InputStream icon) Updates an existing icon of the procedure or sets such if it has not any.
void	setName(java.lang.String name) Sets a new name to the procedure.
void	setShortcut(boolean hasShortcut) Assigns a shortcut to the procedure.
void	setText(java.lang.String text) Changes current text of the procedure with the new one.

Method Detail

getName

java.lang.String getName()
                  throws ManagementException

Gets the name of the procedure object. The name is a mandatory feature of a procedure. The name can be used for a visualization of a procedure. It must be different from null.

Returns:

name of the procedure

Throws:

ManagementException - if system error occurs.

getPath

java.lang.String getPath()
                  throws ManagementException

Gets the path of the procedure object. The path is a mandatory field too. It can be used for visualization of all procedures in a tree structure. If the returned value is an empty String this means that the procedure is located in the root folder.

Returns:

the full path of the procedure

Throws:

ManagementException - if system error occurs.

getText

java.lang.String getText()
                  throws ManagementException

Gets the specified text of the procedure. The text is the most important part of the procedure. It contains the actions to be performed. For more information see the script language definition for a procedure building.

Returns:

the text of this procedure

Throws:

ManagementException - if system error occurs.

setName

void setName(java.lang.String name)
      throws ManagementException

Sets a new name to the procedure. The value of the argument name can't be null. The name must be unique in the scope of the procedure folder. An event with type ProcedureEvent.PROCEDURES_RENAME will be generated if the procedure is successfully renamed.

Parameters:

name - the new name of the procedure

Throws:

ManagementException - if system error occurs, try to rename a procedure and to set already existing name in its folder or the logged user does not imply the proper role.

setText

void setText(java.lang.String text)
      throws ManagementException

Changes current text of the procedure with the new one. The value of the given parameter text cannot be null or empty String. It will observe the rules of the script for a procedure building. An event with type ProcedureEvent.PROCEDURE_MODIFIED will be generated if the procedure text is successfully changed.

Parameters:

text - the new text of the procedure

Throws:

ManagementException - if system error occurs.

setIcon

void setIcon(java.io.InputStream icon)
      throws ManagementException

Updates an existing icon of the procedure or sets such if it has not any. It is supposed the icon parameter contains data of the desired picture to be set as icon image. It there is already an icon; it can be removed when the method is called with null argument. An event with type ProcedureEvent.PROCEDURE_MODIFIED will be generated if the procedure icon is successfully changed.

Parameters:

icon - the data of icon image for the procedure

Throws:

ManagementException - if system error occurs or the logged user does not imply the proper role.

getIcon

java.io.InputStream getIcon()
                     throws ManagementException

Gets the icon that is set for this procedure. The user can make a new instance of the Icon object and visualize it in any GUI application. If the procedure has no icon null will be returned.

Returns:

the InputStream containing the data of the image

Throws:

ManagementException - if system error occurs.

hasIcon

boolean hasIcon()
         throws ManagementException

Indicates whether the procedure has set icon or not. It can be used for lazy initialization of the procedure icon.

Returns:

true if there is a set icon to the procedure and false otherwise

Throws:

ManagementException - if system error occurs.

getArguments

Argument[] getArguments()
                 throws ManagementException

Gets the arguments info of the current procedure. It can be used by GUI applications to customize a parameterized procedure visualization.

Returns:

an array of expected arguments for the procedure; if there are not any an empty array will be returned

Throws:

ManagementException - if system error occurs.

setArguments

void setArguments(Argument[] arguments)
           throws ManagementException

Sets a list of arguments for this procedure. It can be used in the occasions when the procedure is parameterized. An event with type ProcedureEvent.PROCEDURE_MODIFIED will be generated if the procedure arguments are successfully changed. The method calls the method parseProcedureText() and if the returned result is different from the arguments length or there is at least one argument with wrong type a ManagementException shall be thrown. A wrong argument type is not empty String and it is not one from the defined type constants in Argument interface.

Parameters:

arguments - the arguments info

Throws:

ManagementException - if system error occurs or the logged user does not imply the proper role.

hasShortcut

boolean hasShortcut()
             throws ManagementException

Indicates whether this procedure has a shortcut assigned to it.

Returns:

true if there is an assigned shortcut, otherwise false

Throws:

ManagementException - if system error occurs.

See Also:

setShortcut(boolean hasShortcut)

setShortcut

void setShortcut(boolean hasShortcut)
          throws ManagementException

Assigns a shortcut to the procedure. It is used from the mPRM GUI implementation to show all procedures, which have shortcut in the Devices node as buttons in its toolbar. It can be used in other GUIs analogously or can be used to differentiate all procedures in two sets for some reasons. An event with type ProcedureEvent.PROCEDURE_MODIFIED will be generated if the procedure shortcut is added or removed.

Parameters:

hasShortcut - if true this method adds a shortcut to the procedure, otherwise it removes it

Throws:

ManagementException - if system error occurs or the logged use does not imply the proper role.

moveTo

void moveTo(java.lang.String targetFolderPath,
            boolean replace)
     throws ManagementException

Move this procedure to the specified folder. If there is a procedure in the target folder with the same name as this one and the replace argument has value false a ManagementExeption will be thrown. Otherwise the procedure will be replaced with the new one. An event with type ProcedureEvent.PROCEDURE_MOVED will be generated if the procedure is successfully moved to the new folder.

Parameters:

targetFolderPath - the path of the folder where this one to be moved to.

replace - specifies whether to replace a procedure with the same name in the destination folder, if such exists. If true, the existing procedure will be replaced. Otherwise - not.

Throws:

ManagementException - if

• a system error occurs,
• the destination folder with the specified path does not exist,
• there is a procedure in the target folder with name as the moved procedure and the replace flag is false
• the logged user does not imply the proper role