DLV
Class DlvHandler

java.lang.Object
  DLV.DlvHandler

All Implemented Interfaces:

DLV.core.DlvIOHandler

public class DlvHandler

extends java.lang.Object

implements DLV.core.DlvIOHandler

This is a wrapper class that allows to call DLV from a Java program.
Three methods of invocation are supplied: synchronous, model synchronous and asynchronous mode.
In the first method, the thread that starts DLV is blocked until DLV finishes computation and then it is possible to get the output.
In the second and in the third method, we don't wait until DLV terminated computation, but we can check dynamically whether dlv outputs further models.
In the model synchronous case the calling thread is blocked until a new model is computed by dlv or until dlv ends.
In the asynchronous case the calling thread is never blocked.

This class allows to set all DLV invocation parameters.
When a Dlv object is created default DLV invocation parameters are automatically set.

         Ex. How to do a model synchronous dlv invocation

            // prepare input
            Program p=new Program();                       // creates a new program
            p.addString(":- a, not b.");                   // adds a constraint using a String object
            p.addProgramFile("c:\myProgramFile.dl");       // adds a text file containing a program

            // build a manager (a Dlv instance)

            Dlv dlv=new Dlv("c:\dl.exe");                  // builds a manager object and set the dlv executable full pathname

            dlv.setProgram(p);                             // sets input (contained in a Program object)

            // set invocation parameters

            dlv.setNumberOfModels(2);                      // sets the number of models to be generated by DLV
            dlv.setFilter(new String[]{"a"});              // sets a -filter=a option
            dlv.setIncludeFacts(false);                    // sets -nofacts option
            ...

            // call DLV
            try
            {
                 dlv.run(Dlv.MODEL_SYNCHRONOUS);            // run a DLV process and set the output handling method.

                 while(dlv.hasMoreModels())                 // waits while DLV outputs a new model
                 {
                     Model m=dlv.nextModel();                // gets a Model object
                     if(!m.isNoModel())
                     {
                         while(m.hasMorePredicates())         // work with Predicates contained in m
                         {
                             Predicate p=m.nextPredicate()     // gets a Predicate object
                             ... // do something with p
                         }
                     }
                     ... // do something else with m
                 }
                 ...
            }
            catch(DLVException d) { d.printStackTrace(); }
            catch(DLVExceptionUncheked d) { d.printStackTrace(); }
            finally
            {
                System.err.println(dlv.getWarnings());     // handle DLV errors
                ... // do some other error handling operation
            }
            ...

         

Version:

3.0

Author:

Francesco Ricca

See Also:

Program, Model, Predicate, OutputDescriptor

Field Summary

static byte	ASYNCHRONOUS This constant indicates a kind of synchronization method of a DlvHandler instance.
static byte	FINISHED The status of a DlvHandler instance when DLV process terminates a computation.
static byte	FREEZED The status of a DlvHandler instance when DLV process was freezed.
static byte	KILLED The status of a DlvHandler instance when DLV process was killed.
static byte	MODEL_SYNCHRONOUS This constant indicates a kind of synchronization method of a DlvHandler instance.
static byte	READY The status of a DlvHandler instance when DLV is running.
static byte	RUNNING The status of a DlvHandler instance when DLV process is running.
static byte	SYNCHRONOUS This constant indicates a kind of synchronization method of a DlvHandler instance.

Constructor Summary

DlvHandler(DLV.core.AbstractIOImplementation implementation)
Constructs a Dlvhandler object that uses the specified implementation.

DlvHandler(java.lang.String DLV_Path)
Constructs a Dlvhandler object that uses the standard Input Output implementation.

Method Summary

void	addModel(Model m)
void	deFreeze() This function deFreezes the current DLV process.
void	freeze() This function freezes the current DLV process.
int	getCursor() Returns the current cursor position.
static java.lang.String	getDLVWrapperInfo() Returns name and version of this version of the DLV Wrapper.
java.lang.String	getEncoding() Returns the encoding used to exchange data with DLV.
java.lang.String[]	getInvocationParameters()
byte	getMethod() Gets the method used in the last invocation of this Dlvhandler instance (see static constants).
Model	getModel() If exists, returns the Model object currently pointed by the cursor, null otherwise.
Model	getModel(int i) Returns the i-th Model object if exists null otherwise.
OutputDescriptor	getOutputDescriptor() This function allows to get the OutputDescriptor object which describe how to process the output of DLV.
java.lang.String	getPath() Get the current pathname of DLV.
Program	getProgram() This function allows to get the Program object that is the input of DLV.
int	getSize() Returns the current number of models computed by DLV.
byte	getStatus() Gets the status of this DlvHandler instance (see static constants).
java.lang.String	getVersion() This function asks the selected DLV implementation for version information.
java.lang.String	getWarnings() After a DLV invocation, this function returns the warning messages.
boolean	hasMoreModels() Tests If there are more Model object available.
boolean	isFirst() Returns true if the cursor is on the first position, false otherwise.
boolean	isLast() Returns true if the cursor is currently on the last position, false otherwise.
void	kill() This function kills the current DLV process.
Model	nextModel() Returns The next Model object available with respect to the current cursor position.
Model	previousModel() Returns The previous Model object available with respect to the current cursor position.
void	removeModel() This function allows to discard the current Model.
void	removeModel(int i) This function allows to discard the i-th Model object.
void	reset() This function resets the current DlvHandler instance.
void	run() // *************************************** FUNZIONI DI INVOCAZIONE ********************************** /** This function starts DLV in MODEL_SYNCHRONOUS mode.
void	run(byte method) This function starts DLV in "method" mode.
void	setCostBound(java.lang.String costbound) Set the value of costbound option.
void	setCursor(int i) Sets the cursor position. 0 is the first position.
void	setDeterministicConsequences(boolean dc) If set, DLV only computes deterministic consequences.
void	setEncoding(java.lang.String encoding) Sets the encoding used to exchange data with DLV.
void	setFilter(java.lang.String[] filter) Includes only instances of the predicate specified in the filter parameter in output.
void	setFrontEnd(java.lang.String frontend) Set the DLV frontend parameters.
void	setGenerateAllPossibilyModels(boolean pm) If set, DLV outputs all (possibly not optimal) models ignoring weak constraints.
void	setIncludeFacts(boolean ifact) If set, DLV includes facts as part of the output.
void	setInstantiate(boolean i) If set, DLV only ground and out the instantiation.
void	setMaxint(int N) Limit integers to [0,N].
void	setNumberOfModels(int N) If set, DLV computes at most N stable models.
void	setOptimizationOptions(java.lang.String opt) Set the DLV Optimization Options parameters.
void	setOutputDescriptor(OutputDescriptor outputDescriptor) This function allows to set the OutputDescriptor object which describe how to process the output of DLV.
void	setPath(java.lang.String DLV_Path) Set the full pathname of DLV for the next invocation.
void	setPFilter(java.lang.String[] filter) Includes only positive instances of the predicate specified in the filter parameter in output.
void	setProgram(Program p) This function allows to set the Program object that is the input of DLV.
void	signalDlvDeFreeze()
void	signalDlvEnd()
void	signalDlvFreeze()
void	signalDlvKill()
void	signalError(java.lang.Throwable t)

Methods inherited from class java.lang.Object

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

Field Detail

READY

public static final byte READY

The status of a DlvHandler instance when DLV is running.

See Also:

Constant Field Values

RUNNING

public static final byte RUNNING

The status of a DlvHandler instance when DLV process is running.

See Also:

Constant Field Values

FINISHED

public static final byte FINISHED

The status of a DlvHandler instance when DLV process terminates a computation.

See Also:

Constant Field Values

KILLED

public static final byte KILLED

The status of a DlvHandler instance when DLV process was killed.

See Also:

Constant Field Values

FREEZED

public static final byte FREEZED

The status of a DlvHandler instance when DLV process was freezed.

See Also:

Constant Field Values

SYNCHRONOUS

public static final byte SYNCHRONOUS

This constant indicates a kind of synchronization method of a DlvHandler instance. If set when you call a model handling function you will wait until DLV process ends.

See Also:

Constant Field Values

MODEL_SYNCHRONOUS

public static final byte MODEL_SYNCHRONOUS

This constant indicates a kind of synchronization method of a DlvHandler instance. If set when you call a model handling function you will wait until DLV process generate a new model. This is the default method.

See Also:

Constant Field Values

ASYNCHRONOUS

public static final byte ASYNCHRONOUS

This constant indicates a kind of synchronization method of a DlvHandler instance. If set when you call a model handling function you will not wait DLV process. For example if you call getModel() and a DLV has no yet computed a model this method returns null without waiting for termination.

See Also:

Constant Field Values

Constructor Detail

DlvHandler

public DlvHandler(java.lang.String DLV_Path)

Constructs a Dlvhandler object that uses the standard Input Output implementation. (pure java input/output through system pipe).

Parameters:

DLV_Path - Is the DLV's pathname.

DlvHandler

public DlvHandler(DLV.core.AbstractIOImplementation implementation)

Constructs a Dlvhandler object that uses the specified implementation.

Parameters:

implementation - An I/O Implementation.

Method Detail

getDLVWrapperInfo

public static java.lang.String getDLVWrapperInfo()

Returns name and version of this version of the DLV Wrapper.

Returns:

Name and version of this version of the DLV Wrapper.

getInvocationParameters

public java.lang.String[] getInvocationParameters()

Specified by:

getInvocationParameters in interface DLV.core.DlvIOHandler

addModel

public void addModel(Model m)

Specified by:

addModel in interface DLV.core.DlvIOHandler

signalDlvEnd

public void signalDlvEnd()

Specified by:

signalDlvEnd in interface DLV.core.DlvIOHandler

signalDlvKill

public void signalDlvKill()

Specified by:

signalDlvKill in interface DLV.core.DlvIOHandler

signalDlvFreeze

public void signalDlvFreeze()

Specified by:

signalDlvFreeze in interface DLV.core.DlvIOHandler

signalDlvDeFreeze

public void signalDlvDeFreeze()

Specified by:

signalDlvDeFreeze in interface DLV.core.DlvIOHandler

signalError

public void signalError(java.lang.Throwable t)

Specified by:

signalError in interface DLV.core.DlvIOHandler

getEncoding

public java.lang.String getEncoding()

Returns the encoding used to exchange data with DLV.

Specified by:

getEncoding in interface DLV.core.DlvIOHandler

Returns:

The encoding used to exchange data with DLV.

setEncoding

public void setEncoding(java.lang.String encoding)

Sets the encoding used to exchange data with DLV.
If your virtual machine implementation or the specified Input Output implementation do not support the specified encoding an error will be thrown during DLV invocation.

Parameters:

encoding - he name of a supported character encoding.

run

public void run()
         throws DLVInvocationException

// *************************************** FUNZIONI DI INVOCAZIONE ********************************** /** This function starts DLV in MODEL_SYNCHRONOUS mode.

Throws:

DLVInvocationException - If any error is occurred during DLV invocation.

run

public void run(byte method)
         throws DLVInvocationException

This function starts DLV in "method" mode.

Specified by:

run in interface DLV.core.DlvIOHandler

Parameters:

method - a byte which set the invocation method (see static constants).

Throws:

DLVInvocationException - If any error is occurred during DLV invocation.

kill

public void kill()
          throws DLVInvocationException

This function kills the current DLV process. This function does not reset the DlvHandler object status (you can access Models computed until now). If this DlvHandler istance isn't in RUNNING or FREEZED status this function performs no operation.

Throws:

DLVInvocationException - If any error is occurred during function call.

freeze

public void freeze()
            throws DLVInvocationException

This function freezes the current DLV process. This function does not reset the DlvHandler object status (you can access Models computed until now). If this DlvHandler istance isn't in RUNNING status this function performs no operation. You cannot freeze DLV if you use the standard Input Output implementation (pure java input/output through system pipe). This feature cannot be implemented in this case. If you use the standard Input Output implementation and try to call this method an UnsupportedOperationException is thrown.

Throws:

DLVInvocationException - If any error is occurred during function call.

deFreeze

public void deFreeze()
              throws DLVInvocationException

This function deFreezes the current DLV process. This function does not reset the DlvHandler object status (you can access Models computed until now). If this DlvHandler istance isn't in FREEZED status this function performs no operation. You cannot freeze DLV if you use the standard Input Output implementation (pure java input/output through system pipe). This feature cannot be implemented in this case. If you use the standard Input Output implementation and try to call this method an UnsupportedOperationException is thrown.

Throws:

DLVInvocationException - If any error is occurred during function call.

reset

public void reset()
           throws DLVInvocationException

This function resets the current DlvHandler instance. If you call this function, the current DLV process will be killed and the internal data structures of this object will be cleared.

Throws:

DLVInvocationException - If any error is occurred during function call.

getWarnings

public java.lang.String getWarnings()
                             throws DLVInvocationException

After a DLV invocation, this function returns the warning messages.
A warning message can be a standard error message or a database access error.
This function may block the current thread until the warning messages are read.

Returns:

A String which contains the warning messages, null otherwise.

Throws:

DLVInvocationException - If some error is occurred during DLV invocation.

setPath

public void setPath(java.lang.String DLV_Path)

Set the full pathname of DLV for the next invocation. This method has no effect if you do not use the standard input output implementation (pure java input/output through system pipe).

Parameters:

DLV_Path - Is the full pathname of DLV.

getPath

public java.lang.String getPath()

Get the current pathname of DLV. This method returns null if you do not use the standard input output implementation (input/output through system pipe).

Returns:

The current pathname of DLV or null.

getVersion

public java.lang.String getVersion()
                            throws DLVInvocationException

This function asks the selected DLV implementation for version information.

Returns:

A string which contains version informations in DLV output format.

Throws:

DLVInvocationException - If some error is occurred during DLV invocation.

getStatus

public byte getStatus()

Gets the status of this DlvHandler instance (see static constants).

Returns:

The status of this DlvHandler instance: RUNNING if DLV is running; FINISHED if DLV process terminated execution; KILLED if DLV process was killed; FREEZED if DLV process was freezed.

getMethod

public byte getMethod()

Gets the method used in the last invocation of this Dlvhandler instance (see static constants). If you never invoked DLV this method returns MODEL_SYNCHRONOUS.

Specified by:

getMethod in interface DLV.core.DlvIOHandler

Returns:

The method used in the last invocation of this DlvHandler istance.

hasMoreModels

public boolean hasMoreModels()
                      throws DLVInvocationException

Tests If there are more Model object available.
If DLV is started in SYNCHRONOUS mode, this method blocks the current thread until DLV ends.
If DLV is started in MODEL_SYNCHRONOUS mode, this method blocks the current thread until a new model (or no model) is found.
If DLV is started in ASYNCHRONOUS mode this method never blocks the current thread.

If there are more models (with respect to the current cursor position) this method returns true; false otherwise.
If the current program is inconsistent (the program hasn't models) this function returns true. In this case a NO_MODEL object (which is a Model object) is returned by calling nextModel();
If DLV has been freezed and (with respect to the current cursor position) there are no models availables the java thread calling this method is blocked until deFreeze() method or reset() method is called. (Be cautious using freeze() deadlock scenarios could occurr)

Returns:

true if there are more Model object (with respect to the current cursor position); false otherwise.

Throws:

DLVInvocationException - If any error occurs while DLV is running.

NoModelsComputed - If DLV has been never executed.

nextModel

public Model nextModel()
                throws DLVInvocationException

Returns The next Model object available with respect to the current cursor position. The cursor moves a position down. If DLV is started in SYNCHRONOUS mode, this method blocks the current thread until DLV ends. If DLV is started in MODEL_SYNCHRONOUS mode, this method may block the current thread until a new model (or no model) is found. If DLV is started in ASYNCHRONOUS mode this method never blocks the current thread. If DLV has been freezed and (with respect to the current cursor position) there are no models availables the java thread calling this method is blocked until deFreeze() method or reset() method is called. (Be cautious using freeze() deadlock scenarios could occurr)

Returns:

The next Model object available or null if DLV doesn't find another model (in this case the cursor doesn't move).

Throws:

DLVInvocationException - If any error occurs while DLV is running.

NoModelsComputed - If DLV has been never executed.

NoSuchModelException - If you try to get a Model which doesn't exist and DLV status il FINISHED or KILLED.

previousModel

public Model previousModel()

Returns The previous Model object available with respect to the current cursor position. The cursor moves a position up. If DLV is started in SYNCHRONOUS mode, this method blocks the current thread until DLV ends. If DLV is started in MODEL_SYNCHRONOUS or ASYNCHRONOUS mode this method never blocks the current thread.

Returns:

The previous Model object available.

Throws:

NoModelsComputed - If DLV has been never executed.

NoSuchModelException - If you try to get a Model which doesn't exist.

getModel

public Model getModel(int i)

Returns the i-th Model object if exists null otherwise.

Returns:

i-th Model object if exists null otherwise.

Throws:

NoSuchModelException - Is thrown if the i-th isn't a valid position.

NoModelsComputed - If DLV has been never executed.

getModel

public Model getModel()

If exists, returns the Model object currently pointed by the cursor, null otherwise. The cursor doesn't move a position down.

Returns:

If exists, the Model object currently pointed by the cursor, null otherwise.

Throws:

NoModelsComputed - If DLV has been never executed.

NoSuchModelException - Is thrown if the cursor isn't in a valid position.

removeModel

public void removeModel(int i)

This function allows to discard the i-th Model object.

Throws:

NoSuchModelException - Is thrown if the i-th is not a valid position.

NoModelsComputed - If DLV has been never executed.

removeModel

public void removeModel()

This function allows to discard the current Model. The cursor moves a position up (to the (i-1)-th model).

Throws:

NoSuchModelException - Is thrown if, at the moment, there are no currrent models for this program.

NoModelsComputed - If DLV has been never executed.

getCursor

public int getCursor()

Returns the current cursor position. Returns -1, if the cursor is before the first position.

Returns:

the current cursor position.

setCursor

public void setCursor(int i)

Sets the cursor position. 0 is the first position. A negative value for i sets the cursor before the first position.

Parameters:

i - the new cursor position.

Throws:

NoSuchModelException - Is thrown if the i-th isn't a valid position.

NoModelsComputed - If DLV has been never executed.

isFirst

public boolean isFirst()

Returns true if the cursor is on the first position, false otherwise.

Returns:

true if the cursor is on the first position, false otherwise.

Throws:

NoModelsComputed - If DLV has been never executed.

isLast

public boolean isLast()

Returns true if the cursor is currently on the last position, false otherwise. If DLV is RUNNING the last position is the position of the last Model computed. Be cautious if you use this method while DLV is RUNNING.

Returns:

true if the cursor is on the last position, false otherwise.

Throws:

NoModelsComputed - If DLV has been never executed.

getSize

public int getSize()

Returns the current number of models computed by DLV. Be cautious if you use this method while DLV is RUNNING, because the current size may change.

Returns:

The current number of models computed by DLV.

Throws:

NoModelsComputed - If DLV has been never executed.

getOutputDescriptor

public OutputDescriptor getOutputDescriptor()

This function allows to get the OutputDescriptor object which describe how to process the output of DLV.

Specified by:

getOutputDescriptor in interface DLV.core.DlvIOHandler

Returns:

The output descriptor associated with this DlvHandelr.

See Also:

OutputDescriptor

setOutputDescriptor

public void setOutputDescriptor(OutputDescriptor outputDescriptor)

This function allows to set the OutputDescriptor object which describe how to process the output of DLV.

Parameters:

outputDescriptor - an OutputDescriptor object

See Also:

OutputDescriptor

getProgram

public Program getProgram()

This function allows to get the Program object that is the input of DLV.

Specified by:

getProgram in interface DLV.core.DlvIOHandler

setProgram

public void setProgram(Program p)

This function allows to set the Program object that is the input of DLV. Changes will be applied before next run() method call.

Parameters:

p - A program object which will be the input of DLV.

setFrontEnd

public void setFrontEnd(java.lang.String frontend)

Set the DLV frontend parameters.
-FB Brave reasoning
-FC Cautious reasoning
-FD Abductive diagnosis
-FDmin Abductive diagnosis, subset minimal
-FDsingle Abductive diagnosis, single error
-FR Reiter's diagnosis
-FRmin Reiter's diagnosis, subset minimal
-FRsingle Reiter's diagnosis, single error
-FP Planning with "K" Action Language
-FPopt ...find optimistic plans in batch mode
-FPsec ...find secure plans in batch mode
-FPc Planning with "C" Action Language
-FPcheck= Secure Check method . Currently implemented: 1,2
-FPsoundcheck= A sound secure check method.
-FPcompletecheck= A complete secure check method.
-planlength= Maximum plan length for planning frontend
-plancache= Size of the plan cache (number of plans, defaults to 10000)
-FS SQL3
If you set a null value this option will be unsetted.

Parameters:

frontend - Is a String written with DLV invocation syntax.

setCostBound

public void setCostBound(java.lang.String costbound)

Set the value of costbound option. Costbound option finds models with cost less than a given set of values N,..,N (N=_ indicates that no bound is required). If you set a null value this option will be unset.

Parameters:

costbound - is a string like N,...,N.

setDeterministicConsequences

public void setDeterministicConsequences(boolean dc)

If set, DLV only computes deterministic consequences.

Parameters:

dc - if true the -det option is set

setInstantiate

public void setInstantiate(boolean i)

If set, DLV only ground and out the instantiation.

Parameters:

i - if true the -instantiate option is set

setNumberOfModels

public void setNumberOfModels(int N)

If set, DLV computes at most N stable models. If you set a negative integer this option will be unset. (set -n option to )

Parameters:

N - Maximum number of stable models.

setMaxint

public void setMaxint(int N)

Limit integers to [0,N]. (set -N option to N) If you set a negative integer this option will be unset.

Parameters:

N - Is maxint.

setOptimizationOptions

public void setOptimizationOptions(java.lang.String opt)

Set the DLV Optimization Options parameters.
-O0 Disable all optimizations.
-OR[-] Input rewriting.
-OGp[-] Use special grounder for propositional input.
-OGo(0|1|2) Grounding performs (no|simple|advanced)
dynamic body reordering.
-OGs Grounding employs semi-naive evaluation.
-OH[-] Heuristics.
-OM- Special Model Checker mode. Not for general use!
-OMb[-] Model-checking employs novel backtracking technique.
-OP- Disable partial model checking.
-OPf Partial model checking ``forwards''.
-OPb Partial model checking during backtracking.

Default options: -OR -OGp -OGo2 -OGs -OH -OMb -OPb
If you set a null value this option will be unsetted.

Parameters:

opt - is a String in DLV invocation syntax

setFilter

public void setFilter(java.lang.String[] filter)

Includes only instances of the predicate specified in the filter parameter in output. (It works like a concatenation of -filter= option) If you set a null value this option will be unset.

Parameters:

filter - Is an array of predicate names.

setPFilter

public void setPFilter(java.lang.String[] filter)

Includes only positive instances of the predicate specified in the filter parameter in output. (It is like a concatenation of -pfilter= option)
If you set a null value this option will be unsetted.

Parameters:

filter - Is an array of predicate names.

setIncludeFacts

public void setIncludeFacts(boolean ifact)

If set, DLV includes facts as part of the output.

Parameters:

ifact - If true the -facts option is set else -nofacts option is set-

setGenerateAllPossibilyModels

public void setGenerateAllPossibilyModels(boolean pm)

If set, DLV outputs all (possibly not optimal) models ignoring weak constraints.

Parameters:

pm - If true the -wctrace option is set.