messif.utility
Class CoreApplication

java.lang.Object
  extended by messif.utility.CoreApplication

public class CoreApplication
extends java.lang.Object

This class implements a standalone client for MESSIF-enabled algorithms. Via the client, a user can use methods provided in this class. For example, an algorithm is started by algorithmStart(java.io.PrintStream, java.lang.String...). To start the client issue the following command:

      java -classpath MESSIF.jar:<algorithm's jar file or directory> messif.utility.CoreApplication [parameters]
 
The parameters can be any combination of The telnet interface (when cmdport is specified) allows to execute CoreApplication's methods. Automatic (context) help is generated whenever user provides incorrect data. For example, entering empty text on the MESSIF prompt will list all available commands. Type just the command name to get help on its arguments (of course there are commands without arguments that will get executed that way). For example, to get information about the last executed operation a method operationInfo(java.io.PrintStream, java.lang.String...) is offered by CoreApplication. To use it from the command line, do something like:
 .... telnet <localhost> <cmdport>
 MESSIF >>> operationInfo
 Range query .... returned 8 objects
 MESSIF >>> 
 
The control file is another way of issuing application commands. It allows to prepare batches of commands that can be run either immediately after the process is started (see the parameters above) or through the controlFile(java.io.PrintStream, java.lang.String...) method. The control file is a text file with the following syntax. Empty lines or lines beginning with # are ignored. All other lines are actions with the following syntax:
  <actionName> = <methodName | otherActionName1 otherActionName2 ...>
  <actionName>.param.1 = <first parameter of the method methodName>
  <actionName>.param.2 = <second parameter of the method methodName>
  <actionName>.param.3 = <third parameter of the method methodName>
  <actionName>.param.4 = <fourth parameter of the method methodName>
  ...
  <actionName>.repeat = <repeats>
  <actionName>.foreach = <value> <value> ...
  <actionName>.outputFile = <filename>
  <actionName>.assign = <variable name>
  <actionName>.postponeUntil = hh:mm:ss

All parameters, method name and output file are subject to variable expansion. Variables can be specified as additional arguments to controlFile command and referred to using "<" and ">" delimiters. For example:

  execmyop = operationExecute
  execmyop.param.1 = messif.operations.<myop>
  execmyop.param.2 = <myparam1:0>
  execmyop.param.3 = ...
 
This action will execute the operation whose name is provided in the variable myop. If the variable is not set, it is replaced by an empty string, which in this particular case will result in error. Therefore, it is possible to provide a default value for a variable by appending a colon and the default value to the variable name. This is shown in the second parameter in the example above - if the myparam1 variable is not set, the zero value is used for the execmyop.param.2.

The default action name that is looked up in the control file is actions if another name is not provided on command line or by a parameter.


Field Summary
protected  Algorithm algorithm
          Currently running algorithm
protected  java.util.List<Algorithm> algorithms
          List of running algorithms
protected  java.lang.String bindOperationStatsRegexp
          Regular expression for binding OperationStatistics in every operationExecute(java.io.PrintStream, java.lang.String...) call
protected  java.nio.channels.ServerSocketChannel cmdSocket
          Socket used for command communication
protected  AbstractOperation lastOperation
          Last executed operation
protected static java.util.logging.Logger log
          Logger
protected  MethodExecutor methodExecutor
          Internal list of methods that can be executed
protected  java.util.Map<java.lang.String,java.lang.Object> namedInstances
          List of currently created named instances
 
Constructor Summary
protected CoreApplication()
          Create new instance of CoreApplication.
 
Method Summary
 boolean algorithmInfo(java.io.PrintStream out, java.lang.String... args)
          Show some information about the current algorithm.
 boolean algorithmInfoAll(java.io.PrintStream out, java.lang.String... args)
          Show some information about all algorithms.
 boolean algorithmRestore(java.io.PrintStream out, java.lang.String... args)
          Restores a previously serialized algorithm from file.
 boolean algorithmSelect(java.io.PrintStream out, java.lang.String... args)
          Select algorithm to manage.
 boolean algorithmStart(java.io.PrintStream out, java.lang.String... args)
          Creates a new instance of algorithm.
 boolean algorithmStop(java.io.PrintStream out, java.lang.String... args)
          Stops current algorithm and clear the memory used.
 boolean algorithmStopAll(java.io.PrintStream out, java.lang.String... args)
          Stops all algorithms and clear the memory used.
 boolean algorithmStore(java.io.PrintStream out, java.lang.String... args)
          Serialize current algorithm to file.
 boolean algorithmSupportedOperations(java.io.PrintStream out, java.lang.String... args)
          Show information about supported operations for the current algorithm.
 boolean collectGarbage(java.io.PrintStream out, java.lang.String... args)
          Schedules full garbage collection.
 boolean controlFile(java.io.PrintStream out, java.lang.String... args)
          Executes actions from a control file.
protected  boolean controlFileExecuteAction(java.io.PrintStream out, java.util.Properties props, java.lang.String actionName, java.util.Map<java.lang.String,java.lang.String> variables, java.util.Map<java.lang.String,java.io.PrintStream> outputStreams)
          This method reads and executes one action (with name actionName) from the control file (props).
 boolean decode(java.io.PrintStream out, java.lang.String... args)
          Decodes a value to some other value according to a regular expression.
 boolean echo(java.io.PrintStream out, java.lang.String... args)
          Prints the parameters to the output.
 boolean help(java.io.PrintStream out, java.lang.String... args)
          Shows a list of commands with help.
protected static void logException(java.lang.Throwable e)
          Log an exception with a Level.SEVERE level.
 boolean loggingConsoleChangeLevel(java.io.PrintStream out, java.lang.String... args)
          Set the logging level of console.
 boolean loggingFileAdd(java.io.PrintStream out, java.lang.String... args)
          Adds a file for writing loging messages.
 boolean loggingFileChangeLevel(java.io.PrintStream out, java.lang.String... args)
          Changes the loging level of an opened logging file.
 boolean loggingFileRemove(java.io.PrintStream out, java.lang.String... args)
          Removes loging file.
 boolean loggingLevel(java.io.PrintStream out, java.lang.String... args)
          Get or set global level of logging.
static void main(java.lang.String[] args)
          Start a MESSIF application.
 boolean memoryUsage(java.io.PrintStream out, java.lang.String... args)
          Displays the memory usage of this virtual machine.
 boolean methodExecute(java.io.PrintStream out, java.lang.String... args)
          Directly execute a method of the running algorithm.
 boolean namedInstanceAdd(java.io.PrintStream out, java.lang.String... args)
          Creates a new named instance.
 boolean namedInstanceList(java.io.PrintStream out, java.lang.String... args)
          Prints the list of all named instances.
 boolean namedInstanceRemove(java.io.PrintStream out, java.lang.String... args)
          Removes a named instances.
 boolean objectStreamClose(java.io.PrintStream out, java.lang.String... args)
          Closes a named object stream.
 boolean objectStreamOpen(java.io.PrintStream out, java.lang.String... args)
          Open a named stream which allows to read objects from a file.
 boolean objectStreamReset(java.io.PrintStream out, java.lang.String... args)
          Resets a named object stream.
 boolean objectStreamSetParameter(java.io.PrintStream out, java.lang.String... args)
          Sets a value of additional constructor parameter of an opened object stream.
 boolean operationAnswer(java.io.PrintStream out, java.lang.String... args)
          Show the answer of the last executed query operation.
 boolean operationBgExecute(java.io.PrintStream out, java.lang.String... args)
          Executes a specified operation on current algorithm in a new thread (i.e., on the background).
 boolean operationExecute(java.io.PrintStream out, java.lang.String... args)
          Executes a specified operation on current algorithm.
 boolean operationExecuteAgain(java.io.PrintStream out, java.lang.String... args)
          Executes the last operation once more.
 boolean operationChangeAnswerCollection(java.io.PrintStream out, java.lang.String... args)
          Changes the answer collection of the last executed operation.
 boolean operationInfo(java.io.PrintStream out, java.lang.String... args)
          Show information about the last executed operation.
 boolean operationWaitBg(java.io.PrintStream out, java.lang.String... args)
          Synchronize on all operations run on the background.
protected  boolean parseArguments(java.lang.String[] args, int argIndex)
          Internal method called from main method to read parameters and initialize the application.
protected  void processInteractiveSocket(java.nio.channels.SocketChannel connection)
          Process an incoming command-prompt connection.
 boolean propertiesOpen(java.io.PrintStream out, java.lang.String... args)
          Creates a new named properties.
 boolean quit(java.io.PrintStream out, java.lang.String... args)
          Exits this application.
protected  void startApplication(java.lang.String[] args)
          Internal method called from main method to initialize this application.
 boolean statisticsDisable(java.io.PrintStream out, java.lang.String... args)
          Disable (or enable) gathering of statistics.
 boolean statisticsGlobal(java.io.PrintStream out, java.lang.String... args)
          Print all global statistics.
 boolean statisticsGlobalGet(java.io.PrintStream out, java.lang.String... args)
          Gets a value from a global statistic.
 boolean statisticsLastOperation(java.io.PrintStream out, java.lang.String... args)
          Print statistics gathered by the last executed operation.
 boolean statisticsResetGlobal(java.io.PrintStream out, java.lang.String... args)
          Reset all global statistics.
 boolean statisticsSetAutoBinding(java.io.PrintStream out, java.lang.String... args)
          Regular expression on global statistics' names that are bound for each executed operation.
 boolean sum(java.io.PrintStream out, java.lang.String... args)
          Computes a sum of the parameters and prints the result to the output.
protected  java.lang.String usage()
          Returns the command line arguments description.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

protected static java.util.logging.Logger log
Logger


algorithm

protected Algorithm algorithm
Currently running algorithm


algorithms

protected java.util.List<Algorithm> algorithms
List of running algorithms


lastOperation

protected AbstractOperation lastOperation
Last executed operation


bindOperationStatsRegexp

protected java.lang.String bindOperationStatsRegexp
Regular expression for binding OperationStatistics in every operationExecute(java.io.PrintStream, java.lang.String...) call


methodExecutor

protected final MethodExecutor methodExecutor
Internal list of methods that can be executed


namedInstances

protected final java.util.Map<java.lang.String,java.lang.Object> namedInstances
List of currently created named instances


cmdSocket

protected java.nio.channels.ServerSocketChannel cmdSocket
Socket used for command communication

Constructor Detail

CoreApplication

protected CoreApplication()
Create new instance of CoreApplication. The instance is initialized from the main(java.lang.String[]) method.

Method Detail

logException

protected static void logException(java.lang.Throwable e)
Log an exception with a Level.SEVERE level.

Parameters:
e - the exception to log

algorithmStart

public boolean algorithmStart(java.io.PrintStream out,
                              java.lang.String... args)
Creates a new instance of algorithm. This application is only a wrapper class, it doesn't provide any searching or indexing capabilities. To actually store and query data, an algorithm must be created using this method. To implement an algorithm, simply inherit from the Algorithm.

To create algorithm, at least the name of the algorithm class must be provided. Additional parameters are passed to the algorithm's constructor. The following example starts ExampleTree algorithm from package exampletree (do not forget to add a jar file with ExampleTree).

 MESSIF >>> algorithmStart messif.algorithms.impl.ParallelSequentialScan 4
 
Note, that the name of the class is provided fully qualified. The number 4 (after the class name) is passed to the ParallelSequentialScan's constructor (see ParallelSequentialScan for more informations). If some wrong constructor parameters are specified, the constructor annotations are shown for the class.

Parameters:
out - a stream where the application writes information for the user
args - algorithm class followed by constructor arguments
Returns:
true if the method completes successfully, otherwise false

algorithmRestore

public boolean algorithmRestore(java.io.PrintStream out,
                                java.lang.String... args)
Restores a previously serialized algorithm from file. Example of usage:
 MESSIF >>> algorithmRestore /some/where/file/algorithm.serialized
 

Parameters:
out - a stream where the application writes information for the user
args - file name with the serialized algorithm
Returns:
true if the method completes successfully, otherwise false
See Also:
algorithmStore(java.io.PrintStream, java.lang.String...)

algorithmStore

public boolean algorithmStore(java.io.PrintStream out,
                              java.lang.String... args)
Serialize current algorithm to file. Example of usage:
 MESSIF >>> algorithmStore /some/where/file/algorithm.serialized
 

Parameters:
out - a stream where the application writes information for the user
args - file name where the serialized algorithm is stored
Returns:
true if the method completes successfully, otherwise false
See Also:
algorithmRestore(java.io.PrintStream, java.lang.String...)

algorithmStop

public boolean algorithmStop(java.io.PrintStream out,
                             java.lang.String... args)
Stops current algorithm and clear the memory used. Example of usage:
 MESSIF >>> algorithmStop
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

algorithmStopAll

public boolean algorithmStopAll(java.io.PrintStream out,
                                java.lang.String... args)
Stops all algorithms and clear the memory used. Example of usage:
 MESSIF >>> algorithmStopAll
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

algorithmInfo

public boolean algorithmInfo(java.io.PrintStream out,
                             java.lang.String... args)
Show some information about the current algorithm. The text returned by algorithm's Object.toString() method is used. Example of usage:
 MESSIF >>> algorithmInfo
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

algorithmInfoAll

public boolean algorithmInfoAll(java.io.PrintStream out,
                                java.lang.String... args)
Show some information about all algorithms. The text returned by algorithms' Object.toString() method is used. Example of usage:
 MESSIF >>> algorithmInfoAll
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

algorithmSelect

public boolean algorithmSelect(java.io.PrintStream out,
                               java.lang.String... args)
Select algorithm to manage. A parameter with algorithm sequence number is required for specifying, which algorithm to select. Example of usage:
 MESSIF >>> algorithmSelect 0
 

Parameters:
out - a stream where the application writes information for the user
args - the algorithm sequence number
Returns:
true if the method completes successfully, otherwise false
See Also:
algorithmInfoAll(java.io.PrintStream, java.lang.String...)

algorithmSupportedOperations

public boolean algorithmSupportedOperations(java.io.PrintStream out,
                                            java.lang.String... args)
Show information about supported operations for the current algorithm. Example of usage:
 MESSIF >>> algorithmSupportedOperations
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false
See Also:
operationExecute(java.io.PrintStream, java.lang.String...)

operationExecute

public boolean operationExecute(java.io.PrintStream out,
                                java.lang.String... args)
Executes a specified operation on current algorithm. Operations allows querying and manipulating data stored by the algorithm. If no argument for operationExecute is provided, a list of supported operations is shown. In order to execute an operation, an operation instance must be created. Similarly to the algorithmStart(java.io.PrintStream, java.lang.String...), the name of operation's class must be provided and all the additional arguments are passed to its constructor. Example of usage:
 MESSIF >>> operationExecute messif.operations.query.RangeQueryOperation objects 1.3
 
Note that the range query operation requires two parameters - a LocalAbstractObject and a radius. The LocalAbstractObject is usually entered as a next object from a stream (see objectStreamOpen(java.io.PrintStream, java.lang.String...)).

Parameters:
out - a stream where the application writes information for the user
args - operation class followed by constructor arguments
Returns:
true if the method completes successfully, otherwise false

operationBgExecute

public boolean operationBgExecute(java.io.PrintStream out,
                                  java.lang.String... args)
Executes a specified operation on current algorithm in a new thread (i.e., on the background). Operations allows querying and manipulating data stored by the algorithm. If no argument for operationBgExecute is provided, a list of supported operations is shown. In order to execute an operation, an operation instance must be created. Similarly to the algorithmStart(java.io.PrintStream, java.lang.String...), the name of operation's class must be provided and all the additional arguments are passed to its constructor.

Example of usage:

 MESSIF >>> operationBgExecute messif.operations.query.RangeQueryOperation objects 1.3
 

Note that the last operation is updated, however, the control is returned immediately. So if there is another operation executed meanwhile (either background or normal), the results of this operation will be replaced. Use operationWaitBg(java.io.PrintStream, java.lang.String...) method to wait for the operation to finish.

Parameters:
out - a stream where the application writes information for the user
args - operation class followed by constructor arguments
Returns:
true if the method completes successfully, otherwise false

operationWaitBg

public boolean operationWaitBg(java.io.PrintStream out,
                               java.lang.String... args)
Synchronize on all operations run on the background. After this method finishes, there are no running operations on background.

Example of usage:

 MESSIF >>> operationWaitBg
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

operationExecuteAgain

public boolean operationExecuteAgain(java.io.PrintStream out,
                                     java.lang.String... args)
Executes the last operation once more. Note that the operation instance remains the same except for its answer, which might be reset, if true is passed as an argument. The default behavior is not to reset the answer. Statistics are always reset.

Example of usage:

 MESSIF >>> operationExecuteAgain true
 

Parameters:
out - a stream where the application writes information for the user
args - flag whether to reset operation answer
Returns:
true if the method completes successfully, otherwise false

operationInfo

public boolean operationInfo(java.io.PrintStream out,
                             java.lang.String... args)
Show information about the last executed operation. Specifically, the information about the operation created by last call to operationExecute(java.io.PrintStream, java.lang.String...) or operationBgExecute(java.io.PrintStream, java.lang.String...) is shown. Note that the operation might be still running if the operationBgExecute(java.io.PrintStream, java.lang.String...) was used and thus the results might not be complete. Use operationWaitBg(java.io.PrintStream, java.lang.String...) to wait for background operations to finish.

Example of usage:

 MESSIF >>> operationInfo
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

operationChangeAnswerCollection

public boolean operationChangeAnswerCollection(java.io.PrintStream out,
                                               java.lang.String... args)
Changes the answer collection of the last executed operation. This method is valid only if the last executed operation was a descendant of RankingQueryOperation. Example of usage:
 MESSIF >>> operationChangeAnswerCollection messif.objects.util.RankedSortedCollection
 

Parameters:
out - a stream where the application writes information for the user
args - answer collection class followed by its constructor arguments
Returns:
true if the method completes successfully, otherwise false

operationAnswer

public boolean operationAnswer(java.io.PrintStream out,
                               java.lang.String... args)
Show the answer of the last executed query operation. Specifically, the information about the operation created by last call to operationExecute(java.io.PrintStream, java.lang.String...) or operationBgExecute(java.io.PrintStream, java.lang.String...) is shown. Note that the operation might be still running if the operationBgExecute(java.io.PrintStream, java.lang.String...) was used and thus the results might not be complete. Use operationWaitBg(java.io.PrintStream, java.lang.String...) to wait for background operations to finish.

If the last operation was not query operation, this method will fail.

An optional argument is accepted:

Example of usage:

 MESSIF >>> operationAnswer , Locators
 

Parameters:
out - a stream where the application writes information for the user
args - display separator for the list of objects and type of the display
Returns:
true if the method completes successfully, otherwise false

methodExecute

public boolean methodExecute(java.io.PrintStream out,
                             java.lang.String... args)
Directly execute a method of the running algorithm. The method name and its arguments must be provided. Only convertible types can be passed as arguments and if there are several methods with the same name, the first one that matches the number of arguments is selected.

Example of usage:

 MESSIF >>> methodExecute mySpecialAlgorithmMethod 1 false string_string
 

Parameters:
out - a stream where the application writes information for the user
args - method name followed by the values for its arguments
Returns:
true if the method completes successfully, otherwise false

statisticsDisable

public boolean statisticsDisable(java.io.PrintStream out,
                                 java.lang.String... args)
Disable (or enable) gathering of statistics. If passed without parameters, statistics are disabled, so the other statistic methods are useless. If false is passed as parameter, statistics are enabled again. By default, statistics are enabled when application starts.

Example of usage:

 MESSIF >>> statisticsDisable false
 

Parameters:
out - a stream where the application writes information for the user
args - flag whether to disable (true) or enable (false) the statistics
Returns:
true if the method completes successfully, otherwise false

statisticsGlobal

public boolean statisticsGlobal(java.io.PrintStream out,
                                java.lang.String... args)
Print all global statistics. Statistics are shown as name: value.

Three optional arguments are accepted:

Example of usage: To print statistics comma-separated, use:

 MESSIF >>> statisticsGlobal DistanceComputations.* ,
 
To avoid appending newline and append comma, use:
 MESSIF >>> statisticsGlobal DistanceComputations.* , ,
 

Parameters:
out - a stream where the application writes information for the user
args - regular expression to match statistic names and the display separators for the statistic values
Returns:
true if the method completes successfully, otherwise false

statisticsGlobalGet

public boolean statisticsGlobalGet(java.io.PrintStream out,
                                   java.lang.String... args)
Gets a value from a global statistic. If the global statistic does not exist, a new one is created.

Two arguments are required:

Example of usage:

 MESSIF >>> statisticsGlobalGet DistanceComputations messif.statistics.StatisticCounter
 

Parameters:
out - a stream where the application writes information for the user
args - the name and class of the global statistic
Returns:
true if the method completes successfully, otherwise false

statisticsResetGlobal

public boolean statisticsResetGlobal(java.io.PrintStream out,
                                     java.lang.String... args)
Reset all global statistics. An optional parameter is a regular expression applied on names as a filter.

Example of usage:

 MESSIF >>> statisticsResetGlobal DistanceComputations
 

Parameters:
out - a stream where the application writes information for the user
args - regular expression to match statistic names
Returns:
true if the method completes successfully, otherwise false

statisticsLastOperation

public boolean statisticsLastOperation(java.io.PrintStream out,
                                       java.lang.String... args)
Print statistics gathered by the last executed operation. Only the bound statistics are reported. Usually, algorithms bind the relevant statistics automatically, but it can be done explicitely using the statisticsSetAutoBinding(java.io.PrintStream, java.lang.String...) method. Statistics are shown as name: value.

Three optional arguments are accepted:

Example of usage: To print statistics comma-separated, use:

 MESSIF >>> statisticsLastOperation DistanceComputations.* ,
 
To avoid appending newline and append comma, use:
 MESSIF >>> statisticsLastOperation DistanceComputations.* , ,
 

Parameters:
out - a stream where the application writes information for the user
args - regular expression to match statistic names and the display separators for the statistic values
Returns:
true if the method completes successfully, otherwise false

statisticsSetAutoBinding

public boolean statisticsSetAutoBinding(java.io.PrintStream out,
                                        java.lang.String... args)
Regular expression on global statistics' names that are bound for each executed operation. A required argument sets the regular expression applied on names as a filter. If the passed argument is null, the autobinding is disabled.

Example of usage:

 MESSIF >>> statisticsSetAutoBinding .*
 

Parameters:
out - a stream where the application writes information for the user
args - regular expression to match statistic names to bind
Returns:
true if the method completes successfully, otherwise false

objectStreamOpen

public boolean objectStreamOpen(java.io.PrintStream out,
                                java.lang.String... args)
Open a named stream which allows to read objects from a file. The first required argument specifies a file name from which to open the stream. The second required argument gives a fully-qualified name of the stored object class. The third required argument is a name under which the stream is opened.

If the name (third argument) is then specified in place where LocalAbstractObject is argument required, the next object is read from the stream and used as the argument's value.

Example of usage:

 MESSIF >>> objectStreamOpen /my/data/file.xx messif.objects.impl.ObjectByteVectorL1 my_data
 MESSIF >>> operationExecute messif.operations.query.RangeQueryOperation my_data 1.3
 MESSIF >>> operationExecute messif.operations.query.kNNQueryOperation my_data 10
 
Note that the first two objects are read from the stream file /my/data/file.xx, first is used as a query object for the range query, the second is used in the k-NN query. A second example with a special class that requires some additional constructor parameters:
 public class MyClass {
     public MyClass(BufferedReader stream, int value, String text) {
         ... construct object from the stream ...
     }
 }
 MESSIF >>> objectStreamOpen /my/data/file.xx MyClass other_data 10 string_value
 

Parameters:
out - a stream where the application writes information for the user
args - file name to read from, class name of objects to be read from the file, optional name of the object stream, optional additional arguments for the object constructor
Returns:
true if the method completes successfully, otherwise false

objectStreamSetParameter

public boolean objectStreamSetParameter(java.io.PrintStream out,
                                        java.lang.String... args)
Sets a value of additional constructor parameter of an opened object stream. See objectStreamOpen(java.io.PrintStream, java.lang.String...) method for explanation of the concept of additional constructor parameters. This method requires three arguments: The third argument is optional. If not specified, 0 is assumed.

Example of usage:

 MESSIF >>> objectStreamSetParameter other_data new_string_value 1
 

Parameters:
out - a stream where the application writes information for the user
args - name of the object stream, new parameter value to object's contructor, and zero-based index of the parameter
Returns:
true if the method completes successfully, otherwise false

objectStreamClose

public boolean objectStreamClose(java.io.PrintStream out,
                                 java.lang.String... args)
Closes a named object stream. An argument specifying the name of the stream to close is required.

Example of usage:

 MESSIF >>> objectStreamClose my_data
 

Parameters:
out - a stream where the application writes information for the user
args - name of an opened object stream
Returns:
true if the method completes successfully, otherwise false

objectStreamReset

public boolean objectStreamReset(java.io.PrintStream out,
                                 java.lang.String... args)
Resets a named object stream. It means that the objects are read from the beginning of the stream's file again. An argument specifying the name of the stream to reset is required.

Example of usage:

 MESSIF >>> objectStreamReset my_data
 

Parameters:
out - a stream where the application writes information for the user
args - name of an opened object stream
Returns:
true if the method completes successfully, otherwise false

propertiesOpen

public boolean propertiesOpen(java.io.PrintStream out,
                              java.lang.String... args)
Creates a new named properties. The first required argument specifies the name from which to load the properties. The second required argument specifies the name for the properties instance that can be used in other methods. The third optional argument specifies a prefix of keys that the create properties will be restricted to (defaults to null). The fourth optional argument specifies a hashtable of variables that will be replaced in the property values (defaults to null).

Example of usage:

 MESSIF >>> propertiesOpen someparameters.cf my_props begins_with_this host=localhost,port=1000
 

Parameters:
out - a stream where the application writes information for the user
args - the property file, the new name, the restrict prefix (not required) and the variables (not required)
Returns:
true if the method completes successfully, otherwise false

namedInstanceAdd

public boolean namedInstanceAdd(java.io.PrintStream out,
                                java.lang.String... args)
Creates a new named instance. An argument specifying the signature of a constructor, a factory method or a static field is required. Additional argument specifies the name for the instance (defaults to name of the action where this is specified).

Example of usage for constructor, factory method and static field:

 MESSIF >>> namedInstanceAdd messif.objects.impl.ObjectByteVectorL1(1,2,3,4,5,6,7,8,9,10) my_object
 MESSIF >>> namedInstanceAdd messif.utility.ExtendedProperties.getProperties(someparameters.cf) my_props
 MESSIF >>> namedInstanceAdd messif.buckets.index.LocalAbstractObjectOrder.locatorToLocalObjectComparator my_comparator
 

Parameters:
out - a stream where the application writes information for the user
args - the instance constructor, factory method or static field signature and the name to register
Returns:
true if the method completes successfully, otherwise false

namedInstanceList

public boolean namedInstanceList(java.io.PrintStream out,
                                 java.lang.String... args)
Prints the list of all named instances.

Example of usage:

 MESSIF >>> namedInstanceList
 

Parameters:
out - a stream where the application writes information for the user
args - no arguments required
Returns:
true if the method completes successfully, otherwise false

namedInstanceRemove

public boolean namedInstanceRemove(java.io.PrintStream out,
                                   java.lang.String... args)
Removes a named instances. An argument specifying the name of the instance to remove is required.

Example of usage:

 MESSIF >>> namedInstanceRemove my_object
 

Parameters:
out - a stream where the application writes information for the user
args - the name of the instance to remove
Returns:
true if the method completes successfully, otherwise false

loggingLevel

public boolean loggingLevel(java.io.PrintStream out,
                            java.lang.String... args)
Get or set global level of logging. If an argument is passed, the logging level is set. Allowed argument values are names of logging level constants. Otherwise the current logging level is printed out.

Example of usage:

 MESSIF >>> loggingLevel warning
 

Parameters:
out - a stream where the application writes information for the user
args - the new logging level
Returns:
true if the method completes successfully, otherwise false

loggingConsoleChangeLevel

public boolean loggingConsoleChangeLevel(java.io.PrintStream out,
                                         java.lang.String... args)
Set the logging level of console. One argument specifying the logging level is required. Allowed argument values are names of logging level constants. Note that the messages with lower logging level than the current global logging level will not be printed regardless of the console logging level setting.

Example of usage:

 MESSIF >>> loggingConsoleChangeLevel info
 

Parameters:
out - a stream where the application writes information for the user
args - the new logging level
Returns:
true if the method completes successfully, otherwise false

loggingFileAdd

public boolean loggingFileAdd(java.io.PrintStream out,
                              java.lang.String... args)
Adds a file for writing loging messages. The first required argument specifies the name of the file to open. The second argument (defaults to global logging level) specifies the logging level of messages that will be stored in the file. The third argument is a flag if the file is overwritten or appended to if it exists and defaults to appending. The fourth argument specifies whether to use XML or text (the default) format. Allowed argument values are names of logging level constants. The fifth optional argument specifies a regular expression that the message must satisfy in order to be written in this file. The sixth argument specifies the message part that the regular expression is applied to - see Logging.RegexpFilterAgainst values for explanation. Note that the messages with lower logging level than the current global logging level will not be printed regardless of the file's logging level.

Example of usage:

 MESSIF >>> loggingFileAdd myFile.log info true false messif.* CLASS_NAME
 

Parameters:
out - a stream where the application writes information for the user
args - the file name, logging level, append to file flag, simple/xml format selector, regular expression and which part of the message is matched
Returns:
true if the method completes successfully, otherwise false

loggingFileRemove

public boolean loggingFileRemove(java.io.PrintStream out,
                                 java.lang.String... args)
Removes loging file. The file must be previously opened by loggingFileAdd(java.io.PrintStream, java.lang.String...). A required argument specifies the name of the opened logging file to close.

Example of usage:

 MESSIF >>> loggingFileRemove myFile.log
 

Parameters:
out - a stream where the application writes information for the user
args - the logging file name to remove
Returns:
true if the method completes successfully, otherwise false

loggingFileChangeLevel

public boolean loggingFileChangeLevel(java.io.PrintStream out,
                                      java.lang.String... args)
Changes the loging level of an opened logging file. The file must be previously opened by loggingFileAdd(java.io.PrintStream, java.lang.String...). The first required argument specifies the name of the opened logging file to close and the second one the new logging level to set. Note that the messages with lower logging level than the current global logging level will not be printed regardless of the file's logging level.

Example of usage:

 MESSIF >>> loggingFileChangeLevel myFile.log fine
 

Parameters:
out - a stream where the application writes information for the user
args - the logging file name and the new logging level
Returns:
true if the method completes successfully, otherwise false

collectGarbage

public boolean collectGarbage(java.io.PrintStream out,
                              java.lang.String... args)
Schedules full garbage collection. If an optional argument is passed, the application will sleep for the number of miliseconds specified.

Example of usage:

 MESSIF >>> collectGarbage 30000
 

Parameters:
out - a stream where the application writes information for the user
args - number of miliseconds to sleep after the garbage collection
Returns:
true if the method completes successfully, otherwise false

memoryUsage

public boolean memoryUsage(java.io.PrintStream out,
                           java.lang.String... args)
Displays the memory usage of this virtual machine.

Example of usage:

 MESSIF >>> memoryUsage
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

help

public boolean help(java.io.PrintStream out,
                    java.lang.String... args)
Shows a list of commands with help.

Example of usage:

 MESSIF >>> help
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

quit

public boolean quit(java.io.PrintStream out,
                    java.lang.String... args)
Exits this application. Note that there cannot be any algorithms running. All command connections to the application will be closed.

Example of usage:

 MESSIF >>> quit
 

Parameters:
out - a stream where the application writes information for the user
args - this method has no arguments
Returns:
true if the method completes successfully, otherwise false

echo

public boolean echo(java.io.PrintStream out,
                    java.lang.String... args)
Prints the parameters to the output. If the first argument contains "+", it is treated as "inner+final" separators. In the separators, special texts "SPACE" and "NEWLINE" can be specified. All additional parameters are then added to the output separated by the inner separators and followed by the final separator.

Example of usage:

 MESSIF >>> echo NEWLINE+NEWLINE x y z
 

Parameters:
out - a stream where the application writes information for the user
args - output type separator and list of values to print
Returns:
true if the method completes successfully, otherwise false

sum

public boolean sum(java.io.PrintStream out,
                   java.lang.String... args)
Computes a sum of the parameters and prints the result to the output. The first argument is the output format used for printing the value. All computations are done in doubles.

Example of usage:

 MESSIF >>> sum #,##0.## 10 20 30
 

Parameters:
out - a stream where the application writes information for the user
args - format of the result followed by the list of values to sum
Returns:
true if the method completes successfully, otherwise false

decode

public boolean decode(java.io.PrintStream out,
                      java.lang.String... args)
Decodes a value to some other value according to a regular expression. The first argument is the value to be decoded. Second parameter is a regular expression to match the value against. If a match is found, the third parameter is added to output followed by a new line. Otherwise, fourth parameter's regular expression is tried, and so on until a match is found or parameters end.

Example of usage:

 MESSIF >>> decode mySpecVal ^your Y ^my M .* unknown
 

Additionally, a map-based syntax can be used with only two parameters:

 MESSIF >>> decode mySpecVal "^your"="Y","^my"=M,.*="unknown"
 

Parameters:
out - a stream where the application writes information for the user
args - checked value followed by matched and result value pairs
Returns:
true if the method completes successfully, otherwise false

controlFileExecuteAction

protected boolean controlFileExecuteAction(java.io.PrintStream out,
                                           java.util.Properties props,
                                           java.lang.String actionName,
                                           java.util.Map<java.lang.String,java.lang.String> variables,
                                           java.util.Map<java.lang.String,java.io.PrintStream> outputStreams)
This method reads and executes one action (with name actionName) from the control file (props). For a full explanation of the command sytax see CoreApplication.

Parameters:
out - the stream to write the output to
props - the properties with actions
actionName - the name of the action to execute
variables - the current variables' environment
outputStreams - currently opened output streams
Returns:
true if the action was executed successfuly

controlFile

public boolean controlFile(java.io.PrintStream out,
                           java.lang.String... args)
Executes actions from a control file. All commands that can be started from the prompt can be used in control files. The first argument is required to specify the file with commands. Additional arguments are either variable specifications in the form of "varname=value" or the action name that is started (which defaults to "actions"). For a full explanation of the command sytax see CoreApplication.

Example of usage:

 MESSIF >>> controlFile commands.cf var1=100 var2=data.file my_special_action
 

Parameters:
out - a stream where the application writes information for the user
args - file name followed by variable specifications and start action
Returns:
true if the method completes successfully, otherwise false

processInteractiveSocket

protected void processInteractiveSocket(java.nio.channels.SocketChannel connection)
                                 throws java.io.IOException
Process an incoming command-prompt connection.

Parameters:
connection - the connection to process
Throws:
java.io.IOException - if there was a communication error

startApplication

protected void startApplication(java.lang.String[] args)
Internal method called from main method to initialize this application. Basically, this method calls parseArguments(java.lang.String[], int) and prints a usage if false is returned.

Parameters:
args - the command line arguments

usage

protected java.lang.String usage()
Returns the command line arguments description.

Returns:
the command line arguments description

parseArguments

protected boolean parseArguments(java.lang.String[] args,
                                 int argIndex)
Internal method called from main method to read parameters and initialize the application.

Parameters:
args - the command line arguments
argIndex - the index of the argument where to start
Returns:
true if the arguments were valid

main

public static void main(java.lang.String[] args)
Start a MESSIF application.

Parameters:
args - the command line arguments