Package server.restful

package server.restful
Provides the embedded RESTful web server of JSIDPlay2, which exposes SID emulation, playback control, and media streaming capabilities through HTTP/HTTPS and optionally HTTP/2.

Overview

The JSIDPlay2Server class is the entry point of this package and launches an embedded Apache Tomcat instance. It dynamically registers all JSIDPlay2 REST servlets, filters, and security constraints based on configuration files bundled with the application (e.g. tomcat-servlets.list, tomcat-filters.list).

Purpose

This server enables browser-based and mobile access to JSIDPlay2 features such as:

  • Streaming SID tunes as MP3 or RTMP (for mobile clients).
  • Playing C64 demos via remote-controlled emulation.
  • Providing WhatsSID? recognition — identifying which tune is currently played.
  • Serving a web-based JSIDPlay2 interface for playback and configuration.

Server Architecture

  • Container: Embedded Tomcat with dynamic servlet deployment.
  • Protocols: HTTP, HTTPS, optional HTTP/2.
  • Security: Role-based authentication via MemoryRealm (configurable in tomcat-users.xml), supporting user/admin roles.
  • Configuration: All runtime parameters are read from the user's JSIDPlay2 configuration, including keystore credentials for HTTPS and additional directory mappings via directoryServlet.properties.
  • CDI: Basic dependency injection container pre-populating core singletons such as SidDatabase, STIL, and MonitoringThread.

Features

  • Automatic servlet and filter registration using annotations (WebServlet, WebFilter).
  • Integrated request logging via RequestLogFilter.
  • Basic authentication with per-servlet access control annotations (ServletSecurity).
  • Multipart upload handling with configurable limits per servlet.
  • Optional database-backed logging using JPA and DBAppender.
  • Automatic cleanup of inactive RTMP players via PlayerCleanupTimerTask.

Command-Line Integration

The JSIDPlay2Server.JSIDPlay2ServerParameters class defines --whatsSIDDatabase* options for connecting to an external database, which powers the "WhatsSID?" identification service. If provided, the server initializes the JPA persistence layer via Persistence.

Lifecycle

  1. Create an instance using JSIDPlay2Server.getInstance(Configuration).
  2. Call JSIDPlay2Server.start() to initialize Tomcat, security, and all servlets.
  3. Access the REST API or web interface through the configured port(s).
  4. Call JSIDPlay2Server.stop() for a clean shutdown.

Usage Examples

 # Start server with HTTP and HTTPS support
 java -jar jsidplay2.jar --httpPort=8080 --httpsPort=8443

 # Use an external database for WhatsSID
 java -jar jsidplay2.jar \
   --whatsSIDDatabaseDriver=org.postgresql.Driver \
   --whatsSIDDatabaseUrl=jdbc:postgresql://localhost/whatsid \
   --whatsSIDDatabaseUsername=jsid \
   --whatsSIDDatabasePassword=secret
Autor:
Ken Händel