docs(example-soap-calculator): add the tutorial for soap web services…

… integration

.prettierignore

@@ -8,3 +8,4 @@ benchmark/dist*
 sandbox/**/*
 *.json
 CHANGELOG.md
+*.yml

docs/site/Examples-and-tutorials.md

@@ -23,6 +23,9 @@ LoopBack 4 comes with the following example projects:
 - **[rpc-server](https://github.com/strongloop/loopback-next/tree/master/examples/rpc-server)**:
   An example showing how to implement a made-up RPC protocol.
 
+- **[soap-calculator](soap-calculator-tutorial.md)**: Tutorial on integrating
+  SOAP web services.
+
 You can download any of the example projects usig our CLI tool `lb4`:
 
 ```sh
@@ -33,6 +36,7 @@ $ lb4 example
   hello-world: A simple hello-world Application using LoopBack 4.
   log-extension: An example extension project for LoopBack 4.
   rpc-server: A basic RPC server using a made-up protocol.
+  soap-calculator: An example on how to integrate SOAP web services.
 ```
 
 Please follow the instructions in

docs/site/sidebars/lb4_sidebar.yml

@@ -74,6 +74,39 @@ children:
       url: todo-list-tutorial-controller.html
       output: 'web, pdf'
 
+  - title: 'SOAP Web Service Tutorial'
+    url: soap-calculator-tutorial.html
+    output: 'web, pdf'
+    children:
+
+    - title: 'SOAP Web Service Overview'
+      url: soap-calculator-tutorial-web-service-overview.html
+      output: 'web, pdf'
+
+    - title: 'App scaffolding'
+      url: soap-calculator-tutorial-scaffolding.html
+      output: 'web, pdf'
+
+    - title: 'Add a Datasource'
+      url: soap-calculator-tutorial-add-datasource.html
+      output: 'web, pdf'
+
+    - title: 'Add a Service'
+      url: soap-calculator-tutorial-add-service.html
+      output: 'web, pdf'
+
+    - title: 'Add a Controller'
+      url: soap-calculator-tutorial-add-controller.html
+      output: 'web, pdf'
+
+    - title: 'Register the Service'
+      url: soap-calculator-tutorial-register-service.html
+      output: 'web, pdf'
+
+    - title: 'Run and Test it'
+      url: soap-calculator-tutorial-run-and-test.html
+      output: 'web, pdf'
+
 - title: 'Key concepts'
   url: Concepts.html
   output: 'web, pdf'

docs/site/soap-calculator-tutorial-add-controller.md

@@ -0,0 +1,196 @@
+---
+lang: en
+title: 'Add a Controller'
+keywords: LoopBack 4.0, LoopBack 4
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/soap-calculator-add-controller.html
+---
+
+### Add a Controller
+
+![soap-calculator-add-service](../../docs/img/loopback-example-soap-calculator_figure4.png)
+
+Now it is time to add the controller which will make the REST endpoints
+available to client applications through the REST server.
+
+#### Scaffold a BASIC controller
+
+Run the following command to create a **BASIC** controller.
+
+```sh
+lb4 controller calculator
+```
+
+Next, select the **Empty Controller**.
+
+```sh
+? What kind of controller would you like to generate? (Use arrow keys)
+❯ Empty Controller
+  REST Controller with CRUD functions
+```
+
+At this point, you should have two files in the `src/controllers` directory.
+
+- calculator.controller.ts
+- index.ts
+
+The generated Empty controller looks like this. You may remove the comments at
+this point.
+
+```ts
+// Uncomment these imports to begin using these cool features!
+
+// import {inject} from '@loopback/context';
+
+export class CalculatorController {
+  constructor() {}
+}
+```
+
+#### Adding the imports into the Controller
+
+Add the following two lines at the begining of the
+src/controllers/calculator.controller.ts file.
+
+The **get** and **param** are classes imported from the **LB4** REST server and
+used to make the @get and @param decorators available.
+
+The **HttpErrors** is used to help use raise the precondition error whenever we
+find that the client application is trying to divide by zero.
+
+```ts
+import {inject} from '@loopback/core';
+import {get, param, HttpErrors} from '@loopback/rest';
+```
+
+To complete importing the necessary classes, we need to also include the service
+and the interfaces we modeled in the previous step as follows:
+
+```ts
+import {
+  CalculatorService,
+  CalculatorParameters,
+  AddResult,
+  MultiplyResult,
+  DivideResult,
+  SubtractResult,
+} from '../services/calculator.service';
+```
+
+#### Injecting the Service into the Controller
+
+In the constructor method, we inject the service. Please note that the key
+`services.CalculatorService` has not been defined so far, we will inform our
+Application about this key in the last step.
+
+```ts
+export class CalculatorController {
+  constructor(
+    @inject('services.CalculatorService')
+    protected calculatorService: CalculatorService,
+  ) {}
+}
+```
+
+#### Creating the end point methods
+
+Now we need to create and end point for each operation. There will be four(4)
+end points in total. Each end point is a method inside the CalculatorController,
+so make sure the next code segments are placed before the last `}` in the file.
+
+##### Adding the Divide end point
+
+Our divide method looks like this initially. Notice we are using the
+`<CalculatorParameters>` for type assertion. The Node.js methods defined in the
+service are available from here due to the dependency injection available
+through out **LB4**.
+
+```ts
+ async divide(intA: number,intB: number): Promise<DivideResult> {
+    //Preconditions
+    if (intB === 0) {
+      throw new HttpErrors.PreconditionFailed('Cannot divide by zero');
+    }
+    return await this.calculatorService.Divide(<CalculatorParameters>{
+      intA,
+      intB,
+    });
+  }
+```
+
+Now, if we add the **@GET** decorator we are making it available to the **REST**
+_server_ as follows.
+
+```ts
+  @get('/divide/{arg1}/{arg2}')
+   async divide(intA: number,intB: number): Promise<DivideResult> {
+```
+
+Finally we can use the **@param** decorator on the two properties to help us
+validate the data type associated to each parameter. In this case we are making
+sure the client application only sends integer values as the remote SOAP web
+service expects this data type and this is done automatically for us.
+
+The final code looks like as follows:
+
+```ts
+@get('/divide/{arg1}/{arg2}')
+  async divide(
+    @param.path.integer('arg1') intA: number,
+    @param.path.integer('arg2') intB: number,
+  ): Promise<DivideResult> {
+    //Preconditions
+    if (intB === 0) {
+      throw new HttpErrors.PreconditionFailed('Cannot divide by zero');
+    }
+    return await this.calculatorService.Divide(<CalculatorParameters>{
+      intA,
+      intB,
+    });
+  }
+```
+
+##### Adding the remaining end points
+
+Add the following end point methods inside the CalculatorController class above
+the divide end point method.
+
+```ts
+ @get('/multiply/{arg1}/{arg2}')
+  async multiply(
+    @param.path.integer('arg1') intA: number,
+    @param.path.integer('arg2') intB: number,
+  ): Promise<MultiplyResult> {
+    return await this.calculatorService.Multiply(<CalculatorParameters>{
+      intA,
+      intB,
+    });
+  }
+  @get('/add/{arg1}/{arg2}')
+  async add(
+    @param.path.integer('arg1') intA: number,
+    @param.path.integer('arg2') intB: number,
+  ): Promise<AddResult> {
+    return await this.calculatorService.Add(<CalculatorParameters>{
+      intA,
+      intB,
+    });
+  }
+
+  @get('/subtract/{arg1}/{arg2}')
+  async subtract(
+    @param.path.integer('arg1') intA: number,
+    @param.path.integer('arg2') intB: number,
+  ): Promise<SubtractResult> {
+    return await this.calculatorService.Subtract(<CalculatorParameters>{
+      intA,
+      intB,
+    });
+  }
+```
+
+### Navigation
+
+Previous step: [Add a Service](soap-calculator-tutorial-add-service.md)
+
+Next step: [Register the Service](soap-calculator-tutorial-register-service.md)