is-1/README.md

Информационная система управления музыкальными группами

Требования к системе

Функциональные требования

1. Управление объектами MusicBand

   • Создание нового объекта
   • Получение информации об объекте по ID
   • Обновление объекта (модификация атрибутов)
   • Удаление объекта
   • Каскадное удаление связанных объектов

2. Отображение данных

   • Список объектов в виде таблицы с пагинацией
   • Фильтрация по имени (неполное совпадение)
   • Сортировка по любому полю
   • Отображение связанных объектов при просмотре

3. Специальные операции

   • Расчет среднего значения albumsCount
   • Поиск группы с максимальным именем
   • Группировка по numberOfParticipants
   • Добавление сингла к группе
   • Удаление участника из группы

4. Real-time обновления

   • Автоматическая синхронизация при добавлении/изменении/удалении
   • WebSocket для broadcast обновлений всем клиентам
   • Переподключение при разрыве соединения

5. Валидация

   • Все ограничения модели данных (NotNull, Positive, NotBlank)
   • Информативные сообщения об ошибках
   • Валидация на уровне UI, бизнес-логики и базы данных

Технологические требования

1. Backend

   • Jakarta EE 10
   • CDI (Contexts and Dependency Injection)
   • EclipseLink (JPA provider)
   • JAX-RS (REST API)
   • WebSocket
   • PostgreSQL

2. Frontend

   • Vanilla JavaScript (ES6+)
   • HTML5
   • CSS3
   • WebSocket client

Архитектура системы

Структура проекта

ru.akarpov.is1/
├── entity/               # Сущности JPA
│   ├── MusicBand.java
│   ├── Coordinates.java
│   ├── Album.java
│   ├── Person.java
│   ├── Location.java
│   └── enums/
├── repository/           # Слой доступа к данным
│   ├── GenericRepository.java
│   ├── MusicBandRepository.java
│   └── MusicBandRepositoryImpl.java
├── service/              # Бизнес-логика
│   └── MusicBandService.java
├── rest/                 # REST контроллеры
│   ├── MusicBandResource.java
│   └── DatabaseTestResource.java
├── websocket/            # WebSocket endpoints
│   └── WebSocketResource.java
└── config/               # Конфигурация
    ├── JaxRsConfig.java
    ├── CorsFilter.java
    ├── CDIProducer.java
    └── JacksonConfig.java

Слои приложения

1. Entity Layer (Сущности)

• JPA-аннотированные классы
• Валидация с Jakarta Validation
• Связи между сущностями (OneToOne, CascadeType.ALL)
• Автогенерация ID через sequences

2. Repository Layer (Репозитории)

• Generic интерфейс для базовых CRUD операций
• Специализированные методы для MusicBand
• Named queries для сложных запросов
• Транзакционность через @Transactional

3. Service Layer (Сервисы)

• Бизнес-логика и валидация
• Координация между репозиториями
• Broadcast WebSocket событий
• Обработка исключений

4. REST Layer (REST API)

• JAX-RS endpoints
• JSON сериализация/десериализация
• Обработка HTTP запросов
• CORS для cross-origin запросов

5. WebSocket Layer

• Real-time коммуникация с клиентами
• Ping/pong для keep-alive
• Управление сессиями
• Broadcast обновлений

Реализация

Основные компоненты

MusicBandRepositoryImpl

Использует:

• EntityManager для операций с БД
• Named queries для оптимизации
• JPQL для динамических запросов
• Pagination для больших результатов

Ключевые методы:

• save() - создание/обновление с merge
• findAllSorted() - с динамической сортировкой
• findByNameContainingSorted() - фильтрация + сортировка
• addSingle() - атомарное увеличение счетчика
• removeParticipant() - атомарное уменьшение с проверкой

MusicBandService

Координирует:

• Валидацию через Bean Validation
• Операции репозитория
• WebSocket broadcast
• Обработку ошибок

Особенности:

• @Transactional для автоматических транзакций
• @Inject для dependency injection
• Custom ValidationException
• Валидация полей сортировки

WebSocketResource

Управляет:

• Множественными WebSocket соединениями
• Scheduled executor для ping/pong
• Автоматическим удалением мертвых соединений
• JSON serialization через Jackson

Механизм работы:

• Периодический ping каждые 30 секунд
• Автоматическая очистка закрытых сессий
• Exponential backoff для переподключений
• Thread-safe операции с Set

Frontend (app.js)

Класс MusicBandApp включает:

• Управление состоянием (пагинация, фильтры, сортировка)
• REST API клиент с обработкой ошибок
• WebSocket клиент с переподключением
• Динамическое обновление UI
• Валидация форм
• Toast уведомления

Ключевые возможности:

• Debounced фильтрация
• Оптимистичное обновление UI
• Корректная конвертация datetime
• Highlighting полей с ошибками
• Автоматическое переподключение WebSocket

База данных

Схема

• PostgreSQL с sequences для ID
• Cascade delete для связанных объектов
• Ограничения NOT NULL, CHECK
• Индексы для оптимизации запросов

Persistence Unit

• JTA data source
• EclipseLink provider
• Connection pooling
• SQL logging для отладки

Конфигурация

CDI Beans

• @ApplicationScoped для синглтонов
• @Produces для factory methods
• Validator для Bean Validation
• ObjectMapper для JSON

CORS Filter

• Разрешение всех origins (*)
• Поддержка preflight OPTIONS
• Необходимые headers

Развертывание

Требования

• Java 17+
• WildFly 26+ / Payara 6+
• PostgreSQL 12+

Конфигурация DataSource

В standalone.xml:

<datasource jndi-name="java:jboss/datasources/PostgreSQLDS">
    <connection-url>jdbc:postgresql://pg:5432/studs</connection-url>
    <driver>postgresql</driver>
    <security>
        <user-name>your_username</user-name>
        <password>your_password</password>
    </security>
</datasource>

Сборка

mvn clean package

Деплой

cp target/is1.war $WILDFLY_HOME/standalone/deployments/

API Endpoints

REST API

• GET /api/music-bands - список групп (с пагинацией, фильтрацией, сортировкой)
• GET /api/music-bands/{id} - получить группу по ID
• POST /api/music-bands - создать группу
• PUT /api/music-bands/{id} - обновить группу
• DELETE /api/music-bands/{id} - удалить группу
• GET /api/music-bands/statistics/average-albums - средний albumsCount
• GET /api/music-bands/statistics/max-name - группа с макс. именем
• GET /api/music-bands/statistics/group-by-participants - группировка
• POST /api/music-bands/{id}/add-single - добавить сингл
• POST /api/music-bands/{id}/remove-participant - удалить участника

WebSocket

• ws://host/is1/websocket/bands - real-time обновления

Формат сообщения:

{
  "type": "band_update",
  "action": "create|update|delete",
  "data": {...},
  "timestamp": 1234567890
}

Известные особенности

1. WebSocket переподключение - автоматическое с exponential backoff
2. Валидация дат - establishmentDate должен быть после 1900 и не в будущем
3. Cascade delete - при удалении группы удаляются связанные объекты
4. Atomic operations - addSingle и removeParticipant выполняются атомарно
5. Real-time sync - все клиенты получают обновления через WebSocket

Решение проблем

WebSocket не подключается

• Проверьте, что сервер поддерживает WebSocket
• Проверьте CORS настройки
• Убедитесь, что путь правильный

Ошибки валидации

• Все обязательные поля должны быть заполнены
• Числовые поля должны быть положительными
• Даты в корректном формате

Проблемы с базой данных

• Проверьте connection string
• Убедитесь, что PostgreSQL запущен
• Проверьте credentials

Автор

Разработано для курса "Информационные системы", университет ИТМО