Skip to content

Commit a6d91bd

Browse files
thomasWeisethomasWeise
committed
Added Documentation for JSON RPC Examples
1 parent f398a96 commit a6d91bd

3 files changed

Lines changed: 143 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ Distributed systems surround us everywhere today. Their most prominent example i
3131

3232
7. [Web Services](http://github.com/thomasWeise/distributedComputingExamples/tree/master/webServices/)
3333

34-
8. [Message Passing Interface](http://github.com/thomasWeise/distributedComputingExamples/tree/master/mpi/)
34+
8. [JSON RPC](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/)
35+
36+
9. [Message Passing Interface](http://github.com/thomasWeise/distributedComputingExamples/tree/master/mpi/)
3537

3638
Each of the above links leads you to a sub-directory containing a set of examples. Each sub-directory has an own `README.md` file with detailed descriptions.
3739

@@ -57,6 +59,8 @@ Our pursuit of such a technology forces us to first take the de-tour of learning
5759

5860
We then discuss [Web Services](https://en.wikipedia.org/wiki/Web_service). Web services are the basic foundation of many distributed enterprise computing systems and [service-oriented architectures](https://en.wikipedia.org/wiki/Service-oriented_architecture). They are invoked using the [XML](http://github.com/thomasWeise/distributedComputingExamples/tree/master/xml/)-based [SOAP](https://en.wikipedia.org/wiki/SOAP) protocol usually over [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol). Their interface and provided functionality is described via the Web Service Description Language ([WSDL](https://en.wikipedia.org/wiki/Web_Services_Description_Language)), another XML standard. Based on what we already know, we could now send XML data to a Java Servlet via HTTP-POST, parse this data with these Java XML processing technologies, use the same technologies to generate an output XML document, and send this one back as the response of the Java Servlet. Actually, we could even use JavaServer Pages for this purpose. However, there again is a simpler way: We can build services as simple Java objects and publish them to the [Apache Axis2/Java](http://axis.apache.org/axis2/java/core/) server. The server will make them accessible via SOAP and automatically generate WSDL descriptions. These can then be used to generate proxy objects for the client side using, e.g., [Maven](http://maven.apache.org/). We investigate this technology on [several examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/webServices/).
5961

62+
[JSON RPC](https://en.wikipedia.org/wiki/JSON-RPC) is another remote procedure call ([RPC](https://en.wikipedia.org/wiki/Remote_procedure_call)) approach (specified [here](http://json-rpc.org/)) where the exchanged data structures are encoded in the JavaScript Object Notation ([JSON](https://en.wikipedia.org/wiki/JSON)). The data is exchanged via either [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) or [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol). JSON RCPs are similar to web services, but designed to be more light-weighted. We again discuss several [examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/).
63+
6064
Finally, the last tier of our lecture focuses on how the computing power of massive clusters can be utilized for large-scale scientific and engineering computations. Obviously, Web Services, Java Servlets, or even just Java and the HTTP protocol, would be the wrong technologies for that: For large-scale computations, we want to get as efficient as possible with as little overhead as possible. We want to exchange primitive data types efficiently and we want to use communication paradigms not supported by HTTP/TCP, such as broadcasts, multicasts, and asynchronous communication. For this, an implementation of the Message Passing Interface ([MPI](https://en.wikipedia.org/wiki/Message_Passing_Interface)) would be the method of choice. We explore this technology based on [several examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/mpi/) in the C programming language.
6165

6266
All in all, this course will give you a rough understanding of the dominant technologies in different fields of distributed computing, from dynamic websites over company-internal distributed application systems, to distributed engineering and scientific computations. Each field is explored with hands-on examples and you get to test and play with several example technologies.

‎jsonRPC/README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Examples for JSON RPC
2+
3+
[JSON RPC](https://en.wikipedia.org/wiki/JSON-RPC) is a remote procedure call ([RPC](https://en.wikipedia.org/wiki/Remote_procedure_call)) approach (specified [here](http://json-rpc.org/)) where the exchanged data structures are encoded in the JavaScript Object Notation ([JSON](https://en.wikipedia.org/wiki/JSON)). The data is exchanged via either [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) or [TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol).
4+
5+
JSON RCPs are somehow similar to [web services](https://en.wikipedia.org/wiki/Web_service) ([examples](http://github.com/thomasWeise/distributedComputingExamples/tree/master/webServices/)), but are more light-weight (as the data structures smaller and simpler than [SOAP](https://en.wikipedia.org/wiki/SOAP)/[XML](https://en.wikipedia.org/wiki/XML), [examples for XML processing](http://github.com/thomasWeise/distributedComputingExamples/tree/master/xml/java)).
6+
7+
## 1. Examples
8+
9+
### 1.1. (Complex Number) Calculator RPC Server
10+
11+
The complex number [calculator](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/Calculator.java) JSON RPC server offers methods to add, subtract, multiply, and divide [complex numbers](https://en.wikipedia.org/wiki/Complex_number). This example is very similar to the Complex Number Calculator [Web Service](http://github.com/thomasWeise/distributedComputingExamples/tree/master/webServices/) example server.
12+
13+
We introduce a new [data type](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/Complex.java) for representing a complex number in form of a [JavaBean](https://en.wikipedia.org/wiki/JavaBeans).
14+
15+
1. [`Complex.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/Complex.java)
16+
1. [`CalculatorInterface.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/CalculatorInterface.java)
17+
1. [`Calculator.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/Calculator.java)
18+
1. [`CalculatorServlet.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/java/calculator/CalculatorServlet.java)
19+
1. [`web.xml`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/server/src/main/webapp/WEB-INF/web.xml)
20+
21+
You need to compile (via [Maven](http://maven.apache.org/)) and deploy to a [servlet container](https://en.wikipedia.org/wiki/Web_container).
22+
23+
### 1.5. (Complex Number) Calculator Web Service Client
24+
25+
The example client of the calculator JSON RPC introduced above creates two complex numbers `3+11i` and `5+7i`, multiplies then with each other, and prints the result. The multiplication is, of course, done by the web service. This example is very similar to the Complex Number Calculator [Web Service](http://github.com/thomasWeise/distributedComputingExamples/tree/master/webServices/) example client.
26+
27+
The compiled jar archive is a stand-alone executable which you can run via `java -jar calculatorJSONClient-full.jar`.
28+
29+
1. [`Complex.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/client/src/main/java/calculator/Complex.java)
30+
1. [`CalculatorInterface.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/client/src/main/java/calculator/CalculatorInterface.java)
31+
1. [`TestClient.java`](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/examples/calculator/client/src/main/java/calculator/TestClient.java)
32+
33+
## 2. Building and Deployment
34+
35+
### 2.1. Import Project into Eclipse
36+
37+
If you import the projects from this folder in [Eclipse](http://www.eclipse.org), it may first show you a lot of errors. (I recommend using Eclipse Mars or later.) This is a Maven project, so you should "update" it first in Eclipse by
38+
39+
1. Make sure that you can see the `package view` on the left-hand side of the Eclipse window.
40+
2. Right-click on the project (e.g., `calculatorJSONClient`) in the `package view`.
41+
3. In the opening pop-up menu, left-click on `Maven`.
42+
4. In the opening sub-menu, left-click on `Update Project...`.
43+
5. In the opening window...
44+
1. Make sure the project (e.g., `calculatorJSONClient`) is selected.
45+
2. Make sure that `Update project configuration from pom.xml` is selected.
46+
3. You can also select `Clean projects`.
47+
4. Click `OK`.
48+
6. Now the structure of the project in the `package view` should slightly change, the project will be re-compiled, and the errors should disappear.
49+
50+
51+
### 2.2. Build Projects in Eclipse
52+
53+
In this example set, we have three kinds of projects: deployable RPC servers (which need to be deployed into a [servlet container](https://en.wikipedia.org/wiki/Web_container)), stand-alone servers (which can be packaged into executable `jar`s), and clients.
54+
55+
#### 2.2.1. Deployable Servers
56+
57+
Now you can build the deployable server projects, i.e., generate a [`war`](https://en.wikipedia.org/wiki/WAR_file_format_%28Sun%29) files that you can deploy in a [servlet container](https://en.wikipedia.org/wiki/Web_container). For building this `war`, take the following steps:
58+
59+
1. Make sure that you can see the `package view` on the left-hand side of the Eclipse window.
60+
2. Right-click on the project (e.g., `calculatorJSONServer`) in the `package view`.
61+
3. In the opening pop-up menu, choose `Run As`.
62+
4. In the opening sub-menu choose `Run Configurations...`.
63+
5. In the opening window, choose `Maven Build`
64+
6. In the new window `Run Configurations` / `Create, manage, and run configurations`, choose `Maven Build` in the small white pane on the left side.
65+
7. Click `New launch configuration` (the first symbol from the left on top of the small white pane).
66+
8. Write a useful name for this configuration in the `Name` field. You can use this configuration again later.
67+
9. In the tab `Main` enter the `Base directory` of the project, this is the folder called `calculatorJSONServer` containing the Eclipse/Maven project.
68+
10. Under `Goals`, enter `clean compile war:war`. This will build a `war` archive.
69+
11. Click `Apply`
70+
12. Click `Run`
71+
13. The build will start, you will see its status output in the console window.
72+
14. The folder `target` will contain a `war` file, e.g., `calculatorJSONServer.war` after the build. This is the deployable archive with our application.
73+
15. After building the `war` archive, you can now deploy it.
74+
75+
76+
##### 2.2.2. Building a Client (for using a JSON RPC Service) in Eclipse
77+
78+
Now you can build the client projects, i.e., generate the normal [`jar`](https://en.wikipedia.org/wiki/JAR_%28file_format%29) which you can directly execute via `java -jar ...`. If you want to, e.g., build the `calculator/client` example, you would take the following steps:
79+
80+
1. Make sure that you can see the `package view` on the left-hand side of the Eclipse window.
81+
2. Right-click on the project (`calculatorRPCClient`) in the `package view`.
82+
3. In the opening pop-up menu, choose `Run As`.
83+
4. In the opening sub-menu choose `Run Configurations...`.
84+
5. In the opening window, choose `Maven Build`
85+
6. In the new window `Run Configurations` / `Create, manage, and run configurations`, choose `Maven Build` in the small white pane on the left side.
86+
7. Click `New launch configuration` (the first symbol from the left on top of the small white pane).
87+
8. Write a useful name for this configuration in the `Name` field. You can use this configuration again later.
88+
9. In the tab `Main` enter the `Base directory` of the project, this is the folder called `jsonRPC/calculator/client` containing the Eclipse/Maven project.
89+
10. Under `Goals`, enter `clean compile package`. This will build a `jar` archive.
90+
11. Click `Apply`
91+
12. Click `Run`
92+
13. The build will start, you will see its status output in the console window.
93+
14. The folder `target` will contain the files `calculatorJSONClient.jar` and `calculatorJSONClient-full.jar` after the build. The first one requires several libraries in the classpath, the latter one is stand-alone, the one we are after.
94+
95+
If you are in the `target` folder with your command line/terminal, you can now run the client which uses the web service by doing
96+
97+
java -jar calculatorJSONClient-full.jar
98+
99+
Of course, this will work only if the corresponding JSON RPC service is actually running...
100+
101+
102+
### 2.3. Building under Linux without Eclipse
103+
104+
Under Linux, you can also simply run `make_linux.sh` in this project's folder to build the examples without Eclipse, given that you have Maven installed. This will work for any of the examples in this folder.
105+
106+
### 2.4. Deploy
107+
108+
Only the deployable server examples need to be deployed.
109+
110+
### 2.4.1. Deploy to GlassFish
111+
112+
[GlassFish](https://glassfish.java.net/) is a reference implementation of a Java EE 7 application server.
113+
114+
##### 2.4.1.1. Install GlassFish
115+
116+
The following steps are for Linux, but under Windows it will be pretty much the same.
117+
118+
1. Go to the GlassFish website [https://glassfish.java.net/](https://glassfish.java.net/).
119+
2. Select [download](https://glassfish.java.net/download.html).
120+
3. Download the Java EE 7 Web Profile, at the time of this writing, this is [GlassFish 4.1.1](http://download.java.net/glassfish/4.1.1/release/glassfish-4.1.1-web.zip)
121+
4. Unpack the downloaded archive into a folder of your liking (let's call this folder `F`).
122+
5. Open a terminal console and go (`cd`) into folder `F`.
123+
6. In the folder `F` (where you unpackaged the archive), go to sub-folder `glassfish4/bin/`, i.e., to `F/glassfish4/bin/`.
124+
7. Type `./asadmin start-domain`. (Under Windows, type `asadmin start-domain` without the leading `./`.) The server will now start.
125+
8. Under Windows, a window may pop up asking you for allowing the program internet access permission, which you should OK.
126+
9. Open your web browser and visit its configuration page at [`http://localhost:4848`](http://localhost:4848).
127+
128+
##### 2.4.1.2. Deploy `war` to GlassFish
129+
130+
1. Find the `war` file, e.g., `calculatorJSONServer.war` in the folder `target` of this example project.
131+
2. Copy it into the folder `F/glassfish4/glassfish/domains/domain1`.
132+
3. In your web browser, visit [`http://localhost:4848`](http://localhost:4848).
133+
4. Click `Applications` in the menu pane on the right.
134+
5. It should list `calculatorJSONServer`. If you click this menu point, you get a list of the installed servlets

‎webServices/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ The complex number [calculator](http://github.com/thomasWeise/distributedComputi
5151

5252
You need to compile (via [Maven](http://maven.apache.org/)) and deploy (to [Axis2](http://axis.apache.org/axis2/java/core/)) this web service before you can compile the calculator web service client, the next example below.
5353

54+
A similar example has been provided as [JSON RPC](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/).
55+
5456
### 1.5. (Complex Number) Calculator Web Service Client
5557

5658
The example client of the calculator web service introduced above creates two complex numbers `3+11i` and `5+7i`, multiplies then with each other, and prints the result. The multiplication is, of course, done by the web service.
@@ -59,6 +61,8 @@ In order to build the calculator service client, you need to have the calculator
5961

6062
The compiled jar archive is a stand-alone executable which you can run via `java -jar calculatorClient-full.jar`.
6163

64+
A similar example has been provided as [JSON RPC](http://github.com/thomasWeise/distributedComputingExamples/tree/master/jsonRPC/).
65+
6266
## 2. Building and Deployment
6367

6468
Our web service examples are distributed over several independent Maven projects. Actually, there is one project for each example above.

0 commit comments

Comments
 (0)