Введение в игру на Java

1. Обзор

Цель этого вводного руководства — изучить Play Framework и выяснить, как мы можем создать с его помощью веб-приложение.

Play — это высокопроизводительная среда веб-приложений для языков программирования, код которых компилируется и запускается на JVM, в основном на Java и Scala. Он объединяет компоненты и API, необходимые для разработки современных веб-приложений.

2. Настройка игровой платформы

Давайте перейдем на официальную страницу фреймворка Play и загрузим последнюю версию дистрибутива. На момент написания этого руководства последней была версия 2.7.

Мы загрузим ZIP-папку учебника Play Java Hello World и разархивируем файл в удобное место. В корне этой папки мы найдем исполняемый файл sbt , который мы можем использовать для запуска приложения. Кроме того, мы можем установить sbt с их официальной страницы .

Чтобы использовать sbt из скачанной папки, сделаем следующее:

cd /path/to/folder/
./sbt run

Обратите внимание, что мы запускаем скрипт в текущем каталоге, поэтому используется синтаксис ./ .

Если мы установим sbt, то сможем использовать его вместо него:

cd /path/to/folder/
sbt run

После запуска этой команды мы увидим заявление, которое гласит: «(Сервер запущен, нажмите Enter, чтобы остановить и вернуться к консоли…)». Это означает, что наше приложение готово, поэтому теперь мы можем перейти по адресу http://localhost:9000 , где нам будет представлена страница приветствия Play:

3. Анатомия игровых приложений

В этом разделе мы лучше поймем, как устроено приложение Play и для чего используется каждый файл и каталог в этой структуре.

Если вы хотите сразу же бросить себе вызов на простом примере, перейдите к следующему разделу.

Вот файлы и папки, которые мы находим в типичном приложении Play Framework:

├── app                      → Application sources
│   ├── assets               → Compiled Asset sources
│   │   ├── javascripts      → Typically Coffee Script sources
│   │   └── stylesheets      → Typically LESS CSS sources
│   ├── controllers          → Application controllers
│   ├── models               → Application business layer
│   └── views                → Templates
├── build.sbt                → Application build script
├── conf                     → Configurations files and other non-compiled resources (on classpath)
│   ├── application.conf     → Main configuration file
│   └── routes               → Routes definition
├── dist                     → Arbitrary files to be included in your projects distribution
├── lib                      → Unmanaged libraries dependencies
├── logs                     → Logs folder
│   └── application.log      → Default log file
├── project                  → sbt configuration files
│   ├── build.properties     → Marker for sbt project
│   └── plugins.sbt          → sbt plugins including the declaration for Play itself
├── public                   → Public assets
│   ├── images               → Image files
│   ├── javascripts          → Javascript files
│   └── stylesheets          → CSS files
├── target                   → Generated files
│   ├── resolution-cache     → Information about dependencies
│   ├── scala-2.11            
│   │   ├── api              → Generated API docs
│   │   ├── classes          → Compiled class files
│   │   ├── routes           → Sources generated from routes
│   │   └── twirl            → Sources generated from templates
│   ├── universal            → Application packaging
│   └── web                  → Compiled web assets
└── test                     → source folder for unit or functional tests

3.1. Каталог приложений _

Этот каталог содержит исходный код Java, веб-шаблоны и исходники скомпилированных ресурсов — в основном, все исходники и все исполняемые ресурсы.

Каталог app содержит несколько важных подкаталогов, каждый из которых содержит одну часть архитектурного шаблона MVC:

• модели — это бизнес-уровень приложения, файлы в этом пакете, вероятно, будут моделировать наши таблицы базы данных и позволят нам получить доступ к уровню сохраняемости.
• представления — все шаблоны HTML, которые могут быть отображены в браузере, содержатся в этой папке.
• controllers — подкаталог, в котором у нас есть наши контроллеры. Контроллеры — это исходные файлы Java, содержащие действия, которые должны выполняться для каждого вызова API. Действия — это общедоступные методы, которые обрабатывают HTTP-запросы и возвращают такие же результаты, как и ответы HTTP.
• assets — подкаталог, содержащий скомпилированные ресурсы, такие как CSS и javascript. Приведенные выше соглашения об именах являются гибкими, мы можем создавать наши пакеты, например , пакет app/utils . Мы также можем настроить имя пакета app/com/foreach/controllers.

Он также содержит необязательные файлы и каталоги, необходимые конкретному приложению.

3.2. Публичный каталог _

Ресурсы, хранящиеся в общедоступном каталоге, являются статическими активами, которые обслуживаются непосредственно веб-сервером.

Этот каталог обычно имеет три подкаталога для файлов изображений, CSS и JavaScript. Мы рекомендуем организовывать файлы ресурсов таким образом, чтобы обеспечить единообразие во всех приложениях Play.

3.3. Каталог conf _

Каталог conf содержит файлы конфигурации приложения. В application.conf мы поместим большинство свойств конфигурации для приложения Play. Мы определим конечные точки для приложения в route .

Если приложению нужны дополнительные файлы конфигурации, их следует поместить в этот каталог.

3.4. Каталог библиотек _

Каталог lib является необязательным и содержит зависимости от неуправляемых библиотек. Если у нас есть jar-файлы, не указанные в системе сборки, мы помещаем их в этот каталог. Они будут автоматически добавлены в путь к классам приложения.

3.5. Файл build.sbt _

Файл build.sbt — это скрипт сборки приложения. Здесь мы перечисляем зависимости, необходимые для запуска приложения, такие как тестовые и сохраняемые библиотеки.

3.6. Каталог проекта _

Все файлы, которые настраивают процесс сборки на основе SBT, находятся в каталоге проекта .

3.7. Целевой каталог _

Этот каталог содержит все файлы, сгенерированные системой сборки, например, все файлы .class .

Увидев и изучив структуру каталогов для примера Play Framework Hello World, который мы только что скачали, мы теперь можем пройтись по основам фреймворка на примере.

4. Простой пример

В этом разделе мы создадим очень простой пример веб-приложения. Мы будем использовать это приложение, чтобы ознакомиться с основами платформы Play.

Вместо того, чтобы загружать пример проекта и строить из него, давайте посмотрим, как мы можем создать приложение Play Framework, используя команду sbt new .

Давайте откроем командную строку, перейдем к выбранному нами местоположению и выполним следующую команду:

sbt new playframework/play-java-seed.g8

Для этого нам нужно уже установить sbt , как описано в Разделе 2 .

Приведенная выше команда сначала предложит нам имя для проекта. Затем он запросит домен (наоборот, как в соглашении об именах пакетов в Java), который будет использоваться для пакетов. Мы нажимаем Enter , не вводя имя, если хотим сохранить значения по умолчанию, указанные в квадратных скобках.

Приложение, созданное с помощью этой команды, имеет ту же структуру, что и созданное ранее. Поэтому мы можем приступить к запуску приложения, как мы это делали ранее:

cd /path/to/folder/ 
sbt run

Приведенная выше команда после завершения выполнения создаст сервер на порту 9000 для предоставления нашего API , доступ к которому мы можем получить через http://localhost:9000 . Мы должны увидеть сообщение «Добро пожаловать в игру» в браузере.

Наш новый API имеет две конечные точки, которые теперь мы можем опробовать по очереди из браузера. Первая, которую мы только что загрузили, — это корневая конечная точка, которая загружает индексную страницу с сообщением «Добро пожаловать в игру!». сообщение.

Второй, по адресу http://localhost:9000/assets, предназначен для загрузки файлов с сервера путем добавления имени файла к пути. Мы можем протестировать эту конечную точку, получив файл favicon.png , который был загружен вместе с приложением, по адресу http://localhost:9000/assets/images/favicon.png .

5. Действия и контроллеры

Метод Java внутри класса контроллера, который обрабатывает параметры запроса и создает результат для отправки клиенту, называется действием.

Контроллер — это класс Java, расширяющий play.mvc.Controller , который логически группирует действия, которые могут быть связаны с результатами, которые они производят для клиента.

Теперь давайте перейдем к app-parent-dir/app/controllers и обратим внимание на HomeController.java .

Действие index HomeController возвращает веб-страницу с простым приветственным сообщением:

public Result index() {
    return ok(views.html.index.render());
}

Эта веб-страница является шаблоном индекса по умолчанию в пакете представлений:

@main("Welcome to Play") {
  <h1>Welcome to Play!</h1>
}

Как показано выше, страница индекса вызывает основной шаблон. Затем основной шаблон обрабатывает отображение заголовка страницы и тегов тела. Он принимает два аргумента: строку для заголовка страницы и объект Html для вставки в тело страницы.

@(title: String)(content: Html)

<!DOCTYPE html>
<html lang="en">
    <head>
        @* Here's where we render the page title `String`. *@
        <title>@title</title>
        <link rel="stylesheet" media="screen" href="@routes.Assets.versioned("stylesheets/main.css")">
        <link rel="shortcut icon" type="image/png" href="@routes.Assets.versioned("images/favicon.png")">
    </head>
    <body>
        @* And here's where we render the `Html` object containing
         * the page content. *@
        @content

        <script src="@routes.Assets.versioned("javascripts/main.js")" type="text/javascript"></script>
    </body>
</html>

Немного изменим текст в индексном файле:

@main("Welcome to ForEach") {
  <h1>Welcome to Play Framework Tutorial on ForEach!</h1>
}

Перезагрузка браузера даст нам жирный заголовок:

Welcome to Play Framework Tutorial on ForEach!

Мы можем полностью отказаться от шаблона, удалив директиву рендеринга в методе index() HomeController , чтобы мы могли напрямую возвращать обычный текст или текст HTML:

public Result index() {
    return ok("REST API with Play by ForEach");
}

После редактирования кода, как показано выше, в браузере останется только текст. Это будет просто текст без HTML и стилей:

REST API with Play by ForEach

С таким же успехом мы могли бы вывести HTML, заключив текст в теги заголовка <h1></h1> и затем передав текст HTML методу Html.apply . Не стесняйтесь играть с ним.

Давайте добавим конечную точку /foreach/html в маршруты :

GET    /foreach/html    controllers.HomeController.applyHtml

Теперь давайте создадим контроллер, который обрабатывает запросы на этой конечной точке:

public Result applyHtml() {
    return ok(Html.apply("<h1>This text will appear as a heading 1</h1>"));
}

Когда мы посетим http://localhost:9000/foreach/html , мы увидим приведенный выше текст в формате HTML.

Мы манипулировали нашим ответом, настроив тип ответа. Мы рассмотрим эту функцию более подробно в следующем разделе.

Мы также увидели две другие важные функции Play Framework.

Во-первых, перезагрузка браузера отражает самую последнюю версию нашего кода; это потому, что наши изменения кода компилируются на лету.

Во-вторых, Play предоставляет нам вспомогательные методы для стандартных ответов HTTP в классе play.mvc.Results . Примером может служить метод ok() , который возвращает ответ OK HTTP 200 вместе с телом ответа, которое мы передаем ему в качестве параметра. Мы уже использовали метод отображения текста в браузере.

В классе Results есть дополнительные вспомогательные методы, такие как notFound() и badRequest() . ``

6. Манипулирование результатами

Мы получили выгоду от функции согласования контента в Play, даже не осознавая этого. Play автоматически определяет тип содержимого ответа из тела ответа. Вот почему мы смогли вернуть текст в методе ok :

return ok("text to display");

А затем Play автоматически установит для заголовка Content-Type значение text/plain . Хотя в большинстве случаев это работает, мы можем взять на себя управление и настроить заголовок типа контента.

Давайте настроим ответ для действия HomeController.customContentType на text/html :

public Result customContentType() {
    return ok("This is some text content").as("text/html");
}

Этот шаблон подходит для всех типов контента. В зависимости от формата данных, которые мы передаем вспомогательному методу ok , мы можем заменить text/html на text/plain или application/json .

Мы можем сделать что-то похожее на набор заголовков:

public Result setHeaders() {
    return ok("This is some text content")
            .as("text/html")
            .withHeader("Header-Key", "Some value");
}

7. Заключение

В этой статье мы изучили основы Play Framework. Мы также смогли создать базовое веб-приложение Java с помощью Play.

Как обычно, исходный код этого руководства доступен на GitHub .