CiaoJava
Class PLGoal

java.lang.Object
  |
  +--CiaoJava.PLGoal

public class PLGoal
extends java.lang.Object

This class Represents a Prolog goal to be evaluated on a given PLConnection. This class connects to the Prolog side of the interface to manage the evaluation of the goals launched from the Java side. Instances of this class should be generated with the launchGoal method of the PLConnection class.


Constructor Summary
PLGoal(PLConnection where, PLTerm term)
          Goal constructor.
PLGoal(PLConnection where, java.lang.String term)
          Goal constructor.
PLGoal(PLTerm term)
          Goal constructor.
PLGoal(java.lang.String term)
          Goal constructor.
 
Method Summary
 boolean execute()
          Sends to Prolog process a request for the execution of this goal, and returns immediately.
protected  void finalize()
          Destructor.
 PLConnection getConnection()
          Gets connection that this goal uses to communicate to Prolog.
 boolean isStillRunning()
          Checks if Prolog is still running this query, or there are solutions that have not been requested.
 PLTerm nextSolution()
          Sends to Prolog process a request for the next query solution.
 void query()
          Goal query.
 void terminate()
          Terminates this Prolog goal execution.
 java.lang.String toString()
          String representation of a Prolog goal.
 void useModule(PLTerm module)
          This method loads a module in the Prolog process.
 void useModule(java.lang.String module)
          This method loads a module in the Prolog process.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PLGoal

public PLGoal(PLTerm term)
       throws PLException
Goal constructor. Creates a new goal on an already started Prolog process, using the Prolog term represented with term.
Parameters:
term - Prolog term that represents the goal that will be evaluated.
Throws:
PLException - if there is no connection to Prolog.

PLGoal

public PLGoal(PLConnection where,
              PLTerm term)
Goal constructor. Creates a new goal on the where Prolog process, using the Prolog term represented with term.
Parameters:
where - Prolog process on which the goal must be evaluated.
term - Prolog term that represents the goal that will be evaluated.

PLGoal

public PLGoal(java.lang.String term)
       throws java.io.IOException,
              PLException
Goal constructor. Creates a new goal on a already started Prolog process, using the Prolog term represented with term.
Parameters:
term - String containing the representation of a well formed Prolog term that represents the goal that will be evaluated.
Throws:
PLException - if there is no connection to Prolog.

PLGoal

public PLGoal(PLConnection where,
              java.lang.String term)
       throws java.io.IOException,
              PLException
Goal constructor. Creates a new goal on the where Prolog process, using the Prolog term represented with termString string. This string must be a well formed Prolog term; otherwise a PLException will be thrown. This method connects to Prolog to parse the string containing the goal.
Parameters:
where - Prolog process on which the goal must be evaluated.
term - String containing the representation of a well formed Prolog term that represents the goal that will be evaluated.
Method Detail

query

public void query()
           throws java.io.IOException,
                  PLException
Goal query. Evaluates on the PLConnection associated object the goal represented by this object. To obtain the solutions of this goal, the nextSolution() method must be called, once for each solution.
Throws:
IOException, - PLException if there is any problem communicating with the Prolog process, or in the Prolog side (e.g., the predicate to be launched does not exist, or the goal has been launched yet).

nextSolution

public PLTerm nextSolution()
                    throws java.io.IOException,
                           PLException
Sends to Prolog process a request for the next query solution. Returns a Prolog term that corresponds to the goal with the Prolog variables unified with the solution. Later use of this Prolog variable objects will refer the unification performed. If there is no more solutions, all the variables of the goal will be set to their original binding before calling this method. When this method is invoked, Prolog may be still executing the goal: in this case null is returned, and isStillRunning() method must be used to distinguish between a goal that fails, and a goal that is still running, but no solutions are available currently.
Returns:
the term that corresponds to the query, with the variables unified with the solution.
Throws:
IOException - if there are any error on the sockets.
PLException - if there are any error on the Prolog process. If the Prolog goal raises an exception, it is propagated through the interface, and a PLException is raised in the user Java program.

execute

public boolean execute()
                throws java.io.IOException,
                       PLException
Sends to Prolog process a request for the execution of this goal, and returns immediately. This method does not wait until next solution in the Prolog side.
Returns:
true if the goal was launched successfully
Throws:
IOException - if there are any error on the sockets.
PLException - if there are any error on the Prolog process. If the Prolog goal raises an exception, it is propagated through the interface, and a PLException is raised in the user Java program.

isStillRunning

public boolean isStillRunning()
                       throws PLException,
                              java.io.IOException
Checks if Prolog is still running this query, or there are solutions that have not been requested. This method must be used after nextSolution() returns null to ensure that there are no more solutions to request to this goal.
Returns:
true if this query is still running in the Prolog side, or is expecting nextSolution requests.
Throws:
IOException - if there are any error on the sockets.
PLException - if there are any error on the Prolog process. If the Prolog goal raises an exception, it is propagated through the interface, and a PLException is raised in the user Java program.

terminate

public void terminate()
               throws java.io.IOException,
                      PLException
Terminates this Prolog goal execution.
Throws:
java.io.IOException - if there are any error on the socket communication
PLException - if there are any error on the Prolog process

useModule

public void useModule(PLTerm module)
               throws java.io.IOException,
                      PLException
This method loads a module in the Prolog process. This method brings the possibility of loading Prolog modules dynamically. The module to be loaded must be accesible to the Prolog server.
Parameters:
module - Prolog term that represents the name of the module to be loaded. Can be used the library(module) format.
Throws:
java.io.IOException - if there are any I/O error with the sockets
PLException - if there are any error in the Prolog process

useModule

public void useModule(java.lang.String module)
               throws java.io.IOException,
                      PLException
This method loads a module in the Prolog process. This method brings the possibility of loading Prolog modules dynamically. The module to be loaded must be accesible to the Prolog server.
Parameters:
module - String that contains a Prolog term with the name of the module to be loaded. Can be used the library(module) format. The path must be accesible to the Prolog server.
Throws:
java.io.IOException - if there are any I/O error with the sockets
PLException - if there are any error in the Prolog process

finalize

protected void finalize()
                 throws java.io.IOException,
                        PLException,
                        java.lang.Throwable
Destructor. Terminates the Prolog goal and finalizes itself.
Overrides:
finalize in class java.lang.Object

toString

public java.lang.String toString()
String representation of a Prolog goal.
Overrides:
toString in class java.lang.Object
Returns:
A String object representing this Prolog goal.

getConnection

public PLConnection getConnection()
Gets connection that this goal uses to communicate to Prolog.
Returns:
A PLConnection object representing current connection to Prolog side.