How to import the framework on Android Studio

In order to use the framework in your applications you can import it as module on Android Studio.

1. Import the framework module:
   1. Download the framework last released module.
   2. Extract the downloaded file.
   3. In the project view, right-click on your project New > Module.
   4. Select Import Existing Project.
   5. Select the extracted directory.
2. Set the dependency:
   1. In the Android Studio menu: File > Project Structure.
   2. Select your project module (by default called app).
   3. In the Dependencies Tab add as Module Dependency the previously imported framework.

In the following, we detail the actual usage of the framework by means of a running example. In particular we show how to use the framework to develop a simple mobile app that make use of ASP in order to solve the 3-Colouring problem. This problem asks for a valid assignment of colours to the nodes of a graph: given a graph as set of nodes and edges between them, it is "3-colourable" if to each node can be assigned one among three available colours, in such a way that any two nodes directly linked by an edge cannot have the same colour.

The framework can be invoked adding logic programs as strings and as files:

        ASPHandler handler = new DLVHandler();
        handler.addRawInput("col(N,red) | col(N,green) | col(N,blue) :- node(N).");
        handler.addRawInput(":- col(N1,C1), col(N2,C1), edge(N1,N2).");
        handler.addFileInput("my_edb_file.asp");
        handler.setFilter("col");
        handler.start(theContext, myAnswerSetCallback);
                        

First, we create a new instance of an ASPHandler subclass. Then, the program is added as string input, while "my_edb_file.asp" is a file of input facts, added by its path. In addition, a filter option is set on the predicate "col".

Finally, we start the execution of the solver giving as parameter the Android Context (needed to start the Service) and an object which must be an instance of a class implementing AnswerSetCallback.

The framework allows also to add input using objects:

        Edge edge1 = new Edge("node_1","node_2");
        Edge edge2 = new Edge("node_1","node_3");
        handler.addInput(edge1);
        handler.addInput(edge2);
                        

In order to use this feature, the added objects' classes must be implemented as JavaBeans and properly annotated. Basically, the class Edge can be annotated in this way :

        @Predicate("edge")
        public class Edge {
        @Term(0)
        private String node1;
        @Term(1)
        private String node2;
        .....
        }
                        

Once the solver has been started with the given input, the framework offers different ways to gather its result. First, the user has to write a class implementing AnswerSetCallback, and override the abstract method callback(AnswerSets answerSets). The answer sets found by the solver are contained in an AnswerSets object and one can use this object to analyse each AnswerSet returned by the reasoner. Moreover the user can get an AnswerSet as set of objects, previously annotated using the specific annotations.

            public void callback(AnswerSets answerSets) {
                List<AnswerSet> answerSetList=answerSets.getAnswerSetsList();
                for(AnswerSet answerSet:answerSetList){
                    Set<Object> objSet=answerSet.getAnswerObjects();	
                    ....
                }
            }
                        

In our example of 3-colouring, in order to get back the colours assignment in the form of objects, one can implement a class representing the "col" predicate. In this case, this class will be used to convert the "col" facts in the answer sets as instances of this class; this class can be implemented as follows:

        @Predicate("col")
        public class Col {
        @Term(0)
        private String node;
        @Term(1)
        private String colour;
        .....
        }
                        

In order to notify the framework of the existence of the Col class, the user has to register it, calling the registerClass(Class<?> cl) method of the Singleton class ASPMapper, that notify this class to the ASPMapper. The registration is automatic if the input or the fillter are added using Class objects. The framework in a transparent way will map the answer sets into objects taking care of the parsing of the output string returned by the solver. From this point on, the user can manage the answer sets using plain Java objects as she wish.

The framework consists of three different layers:

• The first layer acts like a facade to the user of the framework. It contains all functions needed in order to manage input and output of the ASP solver.
• The second layer acts as a middleware between the facade and the actual solver, providing the native functions that allow to invoke the solver.
• The third layer is the actual ASP solver. It also contains the functions to run and make use of it.

The framework is composed by an hierarchy of classes that interact as shown in the figure.

The abstract class ASPHandler contains the methods to add input in different ways; in particular, the input can be in the form of simple string, files or Java Objects. It contains also a method to set options for the solver. Since the filter option is a very common one, the framework provides a direct way to add it. Indeed, as for the input, the user can set a filter as string using the predicates names, or as a class object representing classes that are annotated as explained hereafter. In addiction, since it acts like an interface to the users, it also contains the method to let the solver starts the reasoning, so this is the class that has to be extended in order to use the framework with an other solver. However, it comes already equipped with an implementation of this class, that uses DLV as solver, the DLVHandler class. In addition, each concrete class that extends ASPHandler should start a proper ASPService.

The abstract class ASPService manages the invocation of the solver and takes care of the results of its computation. The framework provides a concrete implementation of this class, DLVService, which invokes the DLV solver. The source code of DLV has been built using the Android NDK and the DLV code has been optimized for this particular use case, and is linked to the Java code using the JNI as required by the NDK. The following figure depicts an abstract class diagram of an implementation of EmbASP enhanced with two generic solvers.

In order to get back the results obtained by the solver, that is invoked asynchronously, it is needed a callback function, which is automatically called when the computation is terminated. This callback function can be specified implementing the AnswerSetCallback interface.

The answer sets are represented by the class AnswerSets that can be extended in order to parse the specific output of different ASP solvers. While, the concept of answer set is captured by the AnswerSet class.

The framework provides also a mapper able to convert the output string of the solver into Java Objects. This conversion is guided by the annotations of the Java Objects mapped. Indeed, to exploit this functionality, the user has to provides classes with specific annotations and those classes must be implemented as JavaBeans. Basically, there are two types of annotations:

• @Predicate(String name) specify the predicate name and the target of this annotation must be a class.
• @Term(Integer position) specify the term position in the atoms (whose predicate name is specified with @Predicate annotation) and the target of this annotation must be a field of a class.

Moreover, the mapping is done also in the other way around, from objects to strings, so that the input can be also specified as plain Java objects.