Skip to content

Latest commit

 

History

History
173 lines (102 loc) · 9.38 KB

tutorial.asciidoc

File metadata and controls

173 lines (102 loc) · 9.38 KB
Raw

Enterprise Middleware Coursework - Tutorial

This tutorial guides you through the necessary preparation required to begin your Enterprise Middleware coursework. It is very important that you have completed this and are comfortable with the example, before beginning the coursework.

Create Accounts

This section applies to all students

To complete this coursework you will need a GitHub account.

GitHub

GitHub offers the Git version control system as a service. You will use it to host your code and to make it available to the demonstrators. GitHub is very popular in the open-source community and works best when you make your code available to others to view, clone and contribute towards. However, given the confidential nature of your coursework, you will need to use a private repository only accessible by yourself and the demonstrators.

A private repository will be created for you which you will be given access to once the lead demonstrator has been provided with your GitHub username. Once you have created a GitHub account, please email your username to [email protected].

If you do not already have an account you will need to:

  1. Go to: https://github.com/

  2. Fill in your details and select "Sign up for GitHub."

  3. Obtain a private repository.

Tip
 GitHub is a very popular service, and you are quite likely to use it in your professional career; especially if you work with open source software in some capacity.

Environment Setup

This section of the tutorial only applies to students working on their own machines, not those provided by the university!

This coursework depends upon several software packages / development tools. You must ensure you follow the instructions to install the following:

Run Example

Now you will run a simple example. This example provides you with a starting point that you will build on when you come to doing the coursework. Therefore, it is very important that you get this working and become familiar with the code.

Obtain the Contacts-Swagger Quickstart

This section applies to all students

  1. Visit the NewcastleComputingScience/CSC8104-Quarkus github repo release page here.

  2. Click on the Source code (zip) link to obtain the contacts-swagger quickstart

  3. Unzip the download to somewhere on your computer. Be aware this may take some time as there are many files and you are likely writing to your (networked) H drive.

  4. Open a Command Prompt, and go to the root directory in the contacts quickstart you just unzipped.

Note
 You can find a Command Prompt from the Start menu by searching, or start PowerShell using win+x i.

Run the Quickstart

This section applies to all students

Start the service by executing the command provided on the quickstart page here.

Note
 A short demonstration of the sample application is provided here. It is not necessary to watch this video but you may find it useful.

Working with Git

This section applies to all students

You will be using Git in the coursework for regular checkpoint and backup of your code to GitHub. This section will show you how to create a copy of the 'contacts-swagger' example, ready for you to extend in the coursework, and also how to push the code to GitHub.

  • Clone your original private repository from GitHub to a location where you would like to perform your work (correct the url to that of your private repository).

    git clone https://github.com/NCL-CloudComputing/csc8104-your-repo.git

  • Copy the contents of the contacts-swagger quickstart into your private repository, which you downloaded in step Obtain the Contacts-Swagger Quickstart.

  • Now you need to push this code to your git repository on GitHub.

    git add .
git commit -m "Starter project added to repository"
git push origin master

  • You can use a similar method to add new files or changes, commit these changes, and push your commits to the remote repository.

Warning
 Due to recent changes in Git, your default branch may be named master or main. Therefore, be sure to check the default name of your branch when using the above commands.
Tip
 If you are new to Git, you should read Pro Git. Chapters 1-3 should cover all the functionality required for this coursework. Available at: http://git-scm.com/book

Eclipse Setup

This section applies to all students

If you are on a University machine and wish to use Eclipse to edit the contacts-swagger example (and your coursework), you should use the version of Eclipse neon provided on your uni machine.

If you are on your own machine we recommend you visit the Eclipse downloads page and select the "Eclipse IDE for Java EE Developers" which comes with Maven support.

Regardless, once in Eclipse you must add the contacts-swagger example to your workspace using the following steps:

  1. Import the maven project into eclipse.

    1. Within a new workspace, click 'File' → 'Import…​'

    2. Select 'Maven' → 'Existing Maven Projects'

    3. Click on 'Browse' and select the contacts-swagger quickstart folder.

    4. Click 'Finish'

Tip
 You may use other IDEs or editors if you like, but we may not be able to provide support.
Important
 When you first import the project, maven will download all of the project dependencies to an .m2 repository folder on your H drive. This may take a very long time.

Viewing your datasource

During development of your application, you may find it very useful to be able to inspect the contents of your database. To do this, run the ‘DBeaver’ application and create a new database connection by clicking the plug icon shown in the image below.

DBeaver Default Screen

Then with the SQL tab selected, search for H2 and select ‘H2 Server’.

DBeaver New Connection - H2 Server

On the next page, click Edit Driver Settings and paste the following connection string into the URL Template field jdbc:h2:tcp://localhost/mem:quarkus;DB_CLOSE_ON_EXIT=FALSE and click OK and Finish.

DBeaver New Connection - Connection String

Once the connection is created, you can expand the New Connection. To view the created tables and stored data, expand the PUBLIC section, expand Tables and then double-click on the table names to open the view.

DBeaver - Viewing DB

Testing your API

Besides the REST Assured tests run through maven, you will occasionally want to test your API in a more manual fashion, in order to clearly see what information is being sent and received.

It is partly for this purpose that the Contacts-Swagger quickstart uses the Swagger tool to generate API documentation.

Not only does Swagger use @Annotations to automatically generate attractive documentation for API endpoints, but this documentation is interactive. This allows you to run each supported HTTP operation from the documentation webpage with sample input and see the response JSON. An example of swagger documentation can be found here.

Another common method of manual testing of APIs is sending http requests from the command line, using a tool called cURL.

To give you an example of how you might use cURL to see what your API is doing, once the QuickStart is running (locally) you could execute the following commands (in a command prompt):

  • to see a list of all contacts returned, formatted as JSON and accompanied by all HTTP headers.

    curl -v http://localhost:8080/api/contacts/

  • to create a new contact.

    curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{\"firstName\": \"Alice\",\"lastName\": \"Bob\",
\"email\": \"[email protected]\",\"phoneNumber\": \"(231) 111-1111\",\"birthDate\": \"1982-10-26\"}" "http://localhost:8080/api/contacts"

The -v switch instructs curl to display all possible information, whilst the -X switch allows you to specify the HTTP method to be used and -d the data to be sent.

Tip
 If you would like to learn more about how to use cURL, you can refer to the official documentation.