i Platformy Technologiczne Laboratorium nr 4 Java: REST API Aplikacja opracowana w ramach laboratorium nr 4 będzie potrzebna do realizacji laboratorium nr 5 należy zachować przygotowany projekt. Zadanie nr 5 będzie polegało na opracowaniu testów jednostkowych dla aplikacji przygotowanej w ramach poniższego zadania. W czasie pracy należy zwrócić uwagę na podział aplikacji na komponenty oraz implementować krótkie metody o jasno określonym przeznaczeniu. W ramach zadania należy opracować aplikację serwerową, która udostępnia API w architekturze REST do realizacji podstawowych funkcjonalności sklepu internetowego. Dane o produktach i zamówieniach powinny być przechowywane w bazie danych z wykorzystaniem mechanizmów Java Persistence API. Do weryfikacji działania API należy wykorzystać narzędzie Postman. Opis uruchamiania bazy danych Derby (Java DB) oraz instalacji narzędzia Postman znajduje się na końcu instrukcji. Prowadzący określa rodzaj asortymentu dostępnego w sklepie, np.: książki, filmy, płyty CD, komiksy. Przyjmuje się, że sklep oferuje asortyment jednego typu. Klasy encyjne reprezentujące produkty powinny posiadać charakterystyczne pola w zależności od oferowanego asortymentu, przykładowo: książki: o autor, o liczba stron, o wydawca, filmy: o reżyser, o obsada, płyty CD: o wykonawca, o liczba piosenek, o gatunek. o czas trwania, Niezależnie od typu asortymentu klasy encyjne powinny posiadać pola reprezentujące nazwę produktu (np. tytuł książki) i jego cenę oraz pole reprezentujące liczbę sztuk produktu dostępnych do sprzedaży. Aplikacja powinna umożliwiać dodawanie nowych produktów (żądanie typu POST), pobieranie informacji o wszystkich produktach (żądanie typu GET) oraz aktualizację danych produktu, np. zmianę liczby dostępnych sztuk (żądanie typu PUT). Aplikacja powinna przyjmować oraz zwracać dane w formacie JSON (domyślny dla projektów opartych o Spring Boot). Dodatkowo aplikacja powinna umożliwiać składanie zamówień na produkty (POST) oraz pobieranie informacji o zaakceptowanych zamówieniach (GET). Zamówienia powinny być reprezentowane przez osobną klasę encyjną. Pomiędzy zamówieniami i produktami występuje związek wiele-do-wielu (jedno zamówienie może obejmować wiele produktów, a jeden produkt może występować w wielu zamówieniach). Warunkiem akceptacji zamówienia jest dostępność wszystkich zamawianych towarów (należy zweryfikować liczbę dostępnych sztuk). Ponadto prowadzący podaje dwa dodatkowe kryteria poprawności zamówienia, np.: przynajmniej jeden produkt w zamówieniu, brak duplikatów produktów w zamówieniu, nie więcej niż x produktów w zamówieniu, W. Korłub 1
koszt zamówienia nie mniejszy niż x, produkty mogą być zamawiane tylko parami (np. w sklepie z kolumnami głośnikowymi). Jeśli zamówienie nie spełnia któregoś z kryteriów poprawności, powinno zostać odrzucone. Takie zamówienie nie jest zapisywane w bazie danych. Jako punkt startowy do realizacji zadania można wykorzystać aplikację przykładową ze strony przedmiotu. Aplikacja przykładowa przy starcie nawiązuje połączenie z bazą danych, więc konieczne jest uruchomienie bazy Derby (opis w dalszej części instrukcji) przed uruchomieniem aplikacji. Można również utworzyć nowy projekt posługując się stroną http://start.spring.io/. W drugim przypadku należy wybrać zależności: Web, JPA, Lombok, DevTools. Pierwszą operacją po pobraniu projektu (zarówno przykładowego ze strony przedmiotu jak i nowego z serwisu start.spring.io) powinno być jego zbudowanie. Spowoduje to pobranie wszystkich zależności koniecznych do działania aplikacji. Operację tę można zainicjować korzystając bezpośrednio z narzędzia Maven w konsoli tekstowej (w głównym katalogu projektu: $ mvn clean package) lub wykorzystując integrację tego narzędzia w IDE. Przykładowo, w środowisku Netbeans można otworzyć projekt wybierając z menu: File > Open Project (nie jest konieczne importowanie ani tworzenie nowego projektu na podstawie pobranych źródeł środowisko rozpozna projekt w Javie w oparciu o plik pom.xml obecny w pobranej paczce). Jeśli wyświetlony zostanie komunikat zatytułowany Project Problems (poniżej), należy go zignorować klikając w przycisk Close. Problemy będące przyczyną komunikatu zostaną rozwiązane w wyniku zbudowania projektu. Aby zbudować projekt, należy wybrać z menu pozycję: Run > Clean and Build Project. Pierwsze przebudowanie aplikacji zajmuje więcej czasu niż kolejne ze względu na konieczność pobrania z Internetu brakujących zależności. Aby uruchomić aplikację należy wybrać z menu pozycję: Run > Run Project. W przypadku aplikacji przykładowej ze strony przedmiotu należy wcześniej uruchomić bazę danych (opis w dalszej części instrukcji). Aplikacje oparte o Spring Boot domyślnie nasłuchują żądań HTTP na porcie 8080. Jeśli port ten jest zajęty przez inne usługi uruchomione w systemie (wyjątek klasy java.net.bindexception: Address already in use), można go zmienić poprzez dodatkową konfigurację w pliku application.properties w podkatalogu src/main/resources projektu (w środowisku Netbeans: gałąź Other Sources) przykład poniżej. Po wprowadzeniu zmian w pliku konfiguracyjnym application.properties należy zbudować projekt (Run > Build Project) przed kolejną próbą uruchomienia aplikacji. Aplikacja przykładowa ze strony przedmiotu wykorzystuje omówioną konfigurację, aby zmienić port na 9090. Pozwala to uniknąć konfliktu z innymi serwerami i usługami, które są uruchomione w wielu salach laboratoryjnych. W. Korłub 2
Konfiguracja portu serwera HTTP w pliku application.properties #Serwer nasłuchuje na porcie 9090: server.port=9090 Aplikacja przykładowa wykorzystuje moduł DevTools, który przyspiesza pracę z projektem. Przy jego użyciu nie jest konieczne ręczne restartowanie aplikacji po wprowadzeniu zmian w kodzie źródłowym. Serwer wykrywa zmodyfikowane klasy i automatycznie ładuje nową wersję aplikacji. Wystarczy w tym celu skompilować zmienione pliki. Środowisko Netbeans robi to automatycznie po zapisaniu zmian w plikach *.java. W środowisku IntelliJ można zbudować wszystkie zmodyfikowane klasy wybierając z menu pozycję: Build > Build Project. Punktacja Dodawanie nowych produktów: 1 pkt. Pobieranie informacji o wszystkich produktach: 1 pkt. Aktualizacja danych produktu: 1 pkt. Zapisywanie zamówień: 1pkt. Walidacja poprawności zamówienia: 1 pkt. Baza danych Derby (Java DB) W ramach zadania należy wykorzystać bazę danych Derby (Java DB). Można to zrobić uruchamiając i inicjując bazę ręcznie z poziomu wiersza poleceń lub wykorzystując narzędzia zintegrowane w środowisku IDE. W przypadku uruchamiania ręcznego: 1. Należy pobrać wersję dystrybucyjną dostępną pod adresem: ftp://ftp.task.gda.pl/pub/www/apache/dist//db/derby/db-derby-10.13.1.1/ db-derby-10.13.1.1-lib.zip i rozpakować uzyskane archiwum. 2. Następnie należy przejść do podkatalogu lib rozpakowanego archiwum i w wierszu poleceń wywołać polecenie: java -jar derbyrun.jar server start 3. Gdy wyświetli się poniższy komunikat baza Derby jest gotowa do przyjmowania połączeń: Apache Derby Network Server - 10.13.1.1 - (1765088) started and ready to accept connections on port 1527 4. Aby zainicjować pustą bazę danych na potrzeby ćwiczenia, należy w osobnym oknie wiersza poleceń wywołać komendę (również w podkatalogu lib): W systemach z rodziny Windows: java -cp "derbyclient.jar;derbytools.jar" org.apache.derby.tools.ij W systemach z jądrem Linux/macOS: java -cp "derbyclient.jar:derbytools.jar" org.apache.derby.tools.ij 5. Gdy pojawi się znak zachęty "ij>", należy wywołać polecenie: connect 'jdbc:derby://localhost:1527/pt_lab;create=true'; 6. Fraza jdbc:derby://localhost:1527/pt_lab stanowi adres bazy danych do wykorzystania w konfiguracji aplikacji. Zainicjowana w ten sposób baza danych nie wymaga podawania loginu i hasła do połączenia. W. Korłub 3
7. Po znaku zachęty "ij>" można wpisywać zapytania SQL w celu zweryfikowania zawartości bazy danych. W przypadku pracy w środowisku Netbeans: 1. Należy otworzyć panel Services i rozwinąć sekcję Databases: 2. Aby uniknąć problemów z kompatybilnością bazy Derby z różnymi wersjami systemów Windows, należy wykonać dodatkowe kroki: a. Należy pobrać najnowszą wersję bazy Derby i rozpakować archiwum: ftp://ftp.task.gda.pl/pub/www/apache/dist//db/derby/db-derby-10.13.1.1/ db-derby-10.13.1.1-lib.zip. b. Następnie należy kliknąć prawym przyciskiem myszy na pozycji Java DB w panelu Services i wybrać pozycję Properties. c. W oknie właściwości należy w polu Java DB Installation podać ścieżkę do rozpakowanego katalogu z najnowszą wersją bazy Derby. 3. Uruchomienie bazy danych odbywa się za pośrednictwem menu kontekstowego: 4. Następnie można zainicjować pustą bazę danych na potrzeby ćwiczenia: W. Korłub 4
5. Należy podać nazwę bazy danych oraz opcjonalnie login i hasło: 6. Po dodaniu bazy danych w panelu Services widoczne będzie nowe połączenie: Wyświetlony adres do połączenia z bazą danych należy wykorzystać w konfiguracji aplikacji (na rysunku powyżej: jdbc:derby://localhost:1527/pt_lab). 7. Środowisko Netbeans umożliwia przeglądanie tabel istniejących w bazie danych oraz ich zawartości, a także wywoływanie dowolnych zapytań SQL. Konfiguracja połączenia z bazą danych w aplikacji Po zainicjowaniu nowej bazy danych na potrzeby ćwiczenia należy wprowadzić w projekcie aplikacji odpowiednią konfigurację, która umożliwi nawiązanie połączenia. Służy do tego plik application.properties zlokalizowany w podkatalogu src/main/resources projektu (w środowisku Netbeans: gałąź Other sources). W. Korłub 5
Przykładowa konfiguracja połączenia z bazą danych w pliku application.properties #Connection string - adres do polaczenia z baza danych spring.datasource.url=jdbc:derby://localhost:1527/pt_lab #Nazwa uzytkownika bazodanowego i haslo - jesli ustawiono #spring.datasource.username=lab #spring.datasource.password=lab #Sterownik dla bazy Derby i dialekt jezyka SQL spring.datasource.driver-class-name=org.apache.derby.jdbc.clientdriver40 spring.jpa.database-platform=org.hibernate.dialect.derbytensevendialect #Automatyczne generowanie tabel w bazie na podstawie modelu klas encyjnych spring.jpa.hibernate.ddl-auto=update Sterownik dla bazy danych Derby należy wskazać jako zależność projektu. W przypadku projektu budowanego przy użyciu narzędzia Maven wymaganą konfigurację należy umieścić w pliku pom.xml (w środowisku Netbeans: gałąź Project Files): Sterownik JDBC dla bazy Derby jako zależność projektu w pliku pom.xml <dependency> <groupid>org.apache.derby</groupid> <artifactid>derbyclient</artifactid> <version>10.10.1.1</version> <scope>runtime</scope> </dependency> Narzędzie Postman Do testowania aplikacji należy wykorzystać narzędzie Postman, które jest dostępne w sklepie Chrome Web Store. Jeśli Postman nie został wcześniej zainstalowany należy uruchomić przeglądarkę Chrome i przejść pod adres: https://chrome.google.com/webstore/detail/postmanrest-client/fhbjgbiflinjbdggehcddcbncdddomop, a następnie zainstalować rozszerzenie. Instalacja nie wymaga uprawnień administratora. W. Korłub 6