1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
7 This project contains the interfaces for a web service based on gRPC.
12 For gRPC interface, add to your ``pom.xml`` (in the project this part is
18 <groupId>io.grpc</groupId>
19 <artifactId>grpc-netty</artifactId>
20 <version>${grpc.version}</version>
23 <groupId>io.grpc</groupId>
24 <artifactId>grpc-protobuf</artifactId>
25 <version>${grpc.version}</version>
28 <groupId>io.grpc</groupId>
29 <artifactId>grpc-stub</artifactId>
30 <version>${grpc.version}</version>
33 For protobuf-based codegen integrated with the Maven build system, you
34 can use protobuf-maven-plugin :
41 <groupId>kr.motd.maven</groupId>
42 <artifactId>os-maven-plugin</artifactId>
43 <version>1.4.1.Final</version>
48 <groupId>org.xolstice.maven.plugins</groupId>
49 <artifactId>protobuf-maven-plugin</artifactId>
50 <version>0.5.0</version>
52 <protocArtifact>com.google.protobuf:protoc:3.1.0:exe:${os.detected.classifier}</protocArtifact>
53 <pluginId>grpc-java</pluginId>
54 <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
60 <goal>compile-custom</goal>
68 | In order to run the gRPC server and the junit test, you need to download the Manven Ant Task library
69 from `here <https://mvnrepository.com/artifact/org.apache.maven/maven-ant-tasks/2.1.3>`__
70 and copy into ``[verigraph]/lib/``
72 | Due to the fact that the project is intended for Eclipse, you need to
73 install an additional Eclipse plugin because
74 `m2e <https://www.eclipse.org/m2e/>`__ does not evaluate the extension
75 specified in a ``pom.xml``. `Download
76 ``os-maven-plugin-1.5.0.Final.jar`` <http://repo1.maven.org/maven2/kr/motd/maven/os-maven-plugin/1.5.0.Final/os-maven-plugin-1.5.0.Final.jar>`__
77 and put it into the ``<ECLIPSE_HOME>/plugins`` directory.
78 | (As you might have noticed, ``os-maven-plugin`` is a Maven extension,
79 a Maven plugin, and an Eclipse plugin.)
81 If you are using IntelliJ IDEA, you should not have any problem.
83 If you are using other IDEs such as NetBeans, you need to set the system
84 properties ``os-maven-plugin`` sets manually when your IDE is launched.
85 You usually use JVM's ``-D`` flags like the following:
87 | -Dos.detected.name=linux
88 | -Dos.detected.arch=x86\_64
89 | -Dos.detected.classifier=linux-x86\_64
94 Here you can find a brief description about useful files for the gRPC
101 This package includes 2 classes that represent the client and server.
105 | Client of gRPC application. It implements all possible methods
106 necessary for communicate with server.
107 | It prints out the received response.
108 | Moreover it provides some static methods that are used for
109 creating the instances of requests.
113 | Server of gRPC application. It implements all possible methods
114 necessary for communicate with client.
115 | It saves the received request on log.
116 | This server could be accessed by multiple clients, because
117 synchronizes concurrent accesses.
118 | Each method that is possible to call is has the equivalent
119 operation in REST-interface.
123 | This class provides some static methods that are used by
124 ``Service.java`` in order to translate a request into a class that
125 is accepted by Verigraph.
126 | Other methods are used to translate the class of Verigraph in the
127 proper gRPC response.
128 | These functionalities are exploited by test classes.
129 | Furthermore this set of methods is public, so in your application
130 you could call them, even if this should not be useful because
131 ``Client.java`` provides other high-level functions.
133 - *it.polito.grpc.test:*
135 This package includes classes for testing the gRPC application.
137 **GrpcServerTest.java:**
139 | For each possible method we test if works correctly.
140 | We create a fake client (so this test doesn't use the method that
141 are present in client class) and test if it receives the expected
143 | In a nutshell, it tests the methods of Client in case of a fake
145 | Please notice that the test prints some errors but this is
146 intentional, because the program tests also error case.
147 | Indeed, not all methods are tested, because we have another class
148 (ReachabilityTest.java) that is specialized for testing the
153 | This set of tests is intended to control the most common use
154 cases, in particular all methods that are callable in Client and
155 Service class, apart from verifyPolicy for the same reason as
157 | It tries also to raise an exception and verify if the behavior is
160 **MultiThreadTest.java:**
162 | This test creates multiple clients that connect to the server and
163 verify is the result is correct. These methods test the
167 **ReachabilityTest.java:**
169 | This file tests the verification method, it exploits the test case
170 already present in the project and consequently has the certainty
171 of testing not so simple case. In particular it reads the file in
172 "src/main/webapp/json" and use this as starting point.
173 | Some exceptions are thrown in order to verify if they are handled
180 | File containing the description of the service. This includes the
181 definition of all classes used in the application.
182 | Moreover contains the definition of the methods that is possible
184 | Each possible method called by REST API is mapped on a proper gRPC
186 | In case of error a message containing the reason is returned to
188 | More details are available in the section about Proto Buffer.
190 **taget/generated-sources/protobuf/java:**
192 - *io.grpc.verigraph:*
194 This package includes all classes generated from verigraph.proto by
195 means of protoc. For each object you can find 2 classes :
197 **{NameObject}Grpc.java**
199 **{NameObject}GrpcOrBuilder.java**
201 The first is the real implementation, the second is the
204 **taget/generated-sources/protobuf/grpc-java:**
206 - *io.grpc.verigraph:*
208 This package includes a single class generated from verigraph.proto
211 **VerigraphGrpc.java:**
213 This is useful in order to create the stubs that are necessary to
214 communicate both for client and server.
218 This folder includes a jar used for compiling the project with Ant.
220 \*\*maven-ant-tasks-2.1.3.\ jar:**
222 This file is used by build.xml in order to include the maven
227 | Modified in order to add all necessary dependencies. It contains also
228 the build tag used for create the generated-sources folders.
229 | This part is added according to documentation of gRPC for java as
230 explained above in How To Install section.
231 | For further clarification go to `this
232 link <https://github.com/grpc/grpc-java/blob/master/README.md>`__.
236 This ant file permit to run and compile the program in a simple way, it
237 exploits the maven-ant-tasks-2.1.3.jar already present in project.
239 It contains 3 fundamental tasks for gRPC interface:
241 - **build:** compile the program
243 - **run:** run both client and server
245 - **run-client :** run only client
247 - **run-server :** run only server
249 - **run-test :** launch all tests that are present in the package,
250 prints out the partial results and global result.
252 Note that the execution of these tests may take up to 1-2 minutes when
253 successful, according to your computer architecture.
255 More Information About Proto Buffer:
256 ------------------------------------
258 Further clarification about verigraph.proto:
260 - A ``simple RPC`` where the client sends a request to the server using
261 the stub and waits for a response to come back, just like a normal
267 rpc GetGraph (RequestID) returns (GraphGrpc) {}
269 In this case we send a request that contains the id of the graph and the
272 - A ``server-side streaming RPC`` where the client sends a request to
273 the server and gets a stream to read a sequence of messages back. The
274 client reads from the returned stream until there are no more
275 messages. As you can see in our example, you specify a server-side
276 streaming method by placing the stream keyword before the response
282 // Obtains a list of Nodes
283 rpc GetNodes (RequestID) returns (stream NodeGrpc) {}
285 In this case we send a request that contains the id of the graph and the
286 response is a list of Nodes that are inside graph.
288 Further possibilities are available but in this project are not
289 expolied. If you are curious see
290 `here <http://www.grpc.io/docs/tutorials/basic/java.html#defining-the-service>`__.
292 Our ``.proto`` file also contains protocol buffer message type
293 definitions for all the request and response types used in our service
294 methods - for example, here
\92s the ``RequestID`` message type:
301 int64 idNeighbour = 3;
304 The " = 1", " = 2" markers on each element identify the unique "tag"
305 that field uses in the binary encoding. Tag numbers 1-15 require one
306 less byte to encode than higher numbers, so as an optimization you can
307 decide to use those tags for the commonly used or repeated elements,
308 leaving tags 16 and higher for less-commonly used optional elements.
309 Each element in a repeated field requires re-encoding the tag number, so
310 repeated fields are particularly good candidates for this optimization.
312 Protocol buffers are the flexible, efficient, automated solution to
313 solve exactly the problem of serialization. With protocol buffers, you
314 write a .proto description of the data structure you wish to store. From
315 that, the protocol buffer compiler creates a class that implements
316 automatic encoding and parsing of the protocol buffer data with an
317 efficient binary format. The generated class provides getters and
318 setters for the fields that make up a protocol buffer and takes care of
319 the details of reading and writing the protocol buffer as a unit.
320 Importantly, the protocol buffer format supports the idea of extending
321 the format over time in such a way that the code can still read data
322 encoded with the old format.
330 option java_multiple_files = true;
331 option java_package = "io.grpc.verigraph";
332 option java_outer_classname = "VerigraphProto";
335 This .proto file works for protobuf 3, that is slightly different from
336 the version 2, so be careful if you have code already installed.
338 The .proto file starts with a package declaration, which helps to
339 prevent naming conflicts between different projects. In Java, the
340 package name is used as the ``Java package`` unless you have explicitly
341 specified a java\_package, as we have here. Even if you do provide a
342 ``java_package``, you should still define a normal ``package`` as well
343 to avoid name collisions in the Protocol Buffers name space as well as
344 in non-Java languages.
346 | After the package declaration, you can see two options that are
347 Java-specific: ``java_package`` and ``java_outer_classname``.
348 ``java_package`` specifies in what Java package name your generated
349 classes should live. If you don't specify this explicitly, it simply
350 matches the package name given by the package declaration, but these
351 names usually aren't appropriate Java package names (since they
352 usually don't start with a domain name). The ``java_outer_classname``
353 option defines the class name which should contain all of the classes
354 in this file. If you don't give a ``java_outer_classname explicitly``,
355 it will be generated by converting the file name to camel case. For
356 example, "my\_proto.proto" would, by default, use "MyProto" as the
358 | In this case this file is not generated, because
359 ``java_multiple_files`` option is true, so for each message we
360 generate a different class.
362 For further clarifications see
363 `here <https://developers.google.com/protocol-buffers/docs/javatutorial>`__
368 For gRPC interface you need that neo4jmanager service is already
369 deployed, so if this is not the case, please follow the instructions at
371 `link <https://github.com/netgroup-polito/verigraph/blob/a3c008a971a8b16552a20bf2484ebf8717735dd6/README.md>`__.
373 In this version there are some modified files compared to the original
374 `Verigraph project <https://github.com/netgroup-polito/verigraph>`__
376 **it.polito.escape.verify.service.NodeService:**
378 At line 213 we modified the path, because this service is intended to
379 run not only in container, as Tomcat, so we added other possibility that
380 files is placed in src/main/webapp/json/ folder.
382 **it.polito.escape.verify.service.VerificationService:**
384 In the original case it searches for python files in "webapps" folder,
385 that is present if the service is deployed in a container, but absent
386 otherwise. So we added another string that will be used in the case the
387 service doesn't run in Tomcat.
389 **it.polito.escape.verify.databese.DatabaseClass:**
391 Like before we added the possibility that files are not in "webapps"
392 folder, so is modified in order to run in any environment. Modification
393 in method loadDataBase() and persistDatabase().
395 | Pay attention that Python is needed for the project. If it is not
396 already present on your computer, please `download
397 it <https://www.python.org/download/releases/2.7.3/>`__.
398 | It works fine with Python 2.7.3, or in general Python 2.
400 | If you have downloaded a Python version for 64-bit architecture please
401 copy the files in "service/z3\_64" and paste in "service/build" and
403 | because this project works with Python for 32-bit architecture.
405 Python and Z3 must support the same architetcure.
407 Moreover you need the following dependencies installed on your python
410 - "requests" python package ->
411 http://docs.python-requests.org/en/master/
413 - "jsonschema" python package -> https://pypi.python.org/pypi/jsonschema
415 | HINT - to install a package you can raise the following command (Bash
416 on Linux or DOS shell on Windows): python -m pip install jsonschema
417 python -m pip install requests
418 | Pay attention that it is possible that you have to modify the PATH
419 environment variable because is necessary to address the python
420 folder, used for verification phase.
423 `README.rtf <https://gitlab.com/serena.spinoso/DP2.2017.SpecialProject2.gRPC/tree/master>`__
424 and to follow the instructions in order to deploy the Verigraph service.
426 | In the latest version of Maven there is the possibility that the
427 downloaded files are incompatible with Java Version of the project
429 | In this case you have to modify the file ``hk2-parent-2.4.0-b31.pom``
430 under your local Maven repository (e.g.
431 'C:\\Users\\Standard.m2\\repository')
432 | and in the path ``\org\glassfish\hk2\hk2-parent\2.4.0-b31`` find the
433 file and modify at line 1098 (in section ``profile``) the ``jdk``
434 version to ``[1.8,)`` .
436 | Admittedly, the version that is supported by the downloaded files from
437 Maven Dependencies is incompatible with jdk of the project.
438 | So modify the file ``gson-2.3.pom`` in Maven repository, under
439 ``com\google\code\gson\gson\2.3`` directory, in particular line 91,
440 from ``[1.8,`` to ``[1.8,)``.
442 This project was also tested on Linux Ubuntu 15.10.