How jeffersonlab/epics2web works
Project Type and Purpose
• epics2web is a full-stack Java web application packaged as a WAR and intended to run on a servlet container (Tomcat, GlassFish, WildFly).
• Purpose: Act as a gateway between EPICS Channel Access PVs (process variables) and web clients, exposing both REST endpoints (for “caget” style operations) and full-duplex WebSocket channels (for PV monitoring) along with a simple JavaScript client API.
File Structure Analysis
• Top-level build and CI configs: build.gradle, Gradle wrapper, Dockerfile, GitHub Actions workflows, compose.yaml + compose.override.yaml.
• src/main/java/org/jlab/epics2web:
• Application.java: Spring-boot style or Servlet initializer.
• controller/: REST endpoints for GET/monitor operations (CAGet, TestGet, TestMonitor, Overview).
• filter/: HTTP filter for caching and encoding.
• websocket/: ServerEndpoint configuration, session manager, listener, write strategy.
• epics/: ChannelManager, ChannelMonitor, ContextFactory, PvListener (JCA wrappers).
• src/main/webapp:
• JSP views under WEB-INF/views for console, overview, tests.
• Static resources: JS clients (epics2web.js, test-camonitor.js), CSS, images.
• src/integration: integration tests that spin up containers (softIOC, epics2web) and exercise WebSocket & REST.
• examples/: sample Soft IOC .db files, shell scripts to feed channel access values for local testing.
Key Architectural Patterns and Layers
• Containerized micro-services (via Docker Compose):
• softIOC service (EPICS simulation)
• epics2web service (Tomcat + epics2web.war)
• MVC for REST: Controller layer → business logic (ChannelManager) → JCA library → EPICS network
• WebSocket publish/subscribe: MonitorEndpoint + WebSocketSessionManager → push PV updates to browser
• Filter chain: CacheAndEncodingFilter to set caching headers and enforce UTF-8
• Thread pools via CustomPrefixThreadFactory for listener threads
Components & Interactions
a. Main Components
• EPICS PV Source
• SoftIOC container (docker-compose) or real EPICS IOCs on network
• EPICS2Web Server (Tomcat container)
• JCA library (javax.json, jca-2.4.6)
• ChannelManager / ChannelMonitor / ContextFactory
• REST Controllers (CAGet, TestGet)
• WebSocket Stack (MonitorEndpoint, SessionManager, WriteStrategy)
• HTTP Filter (CacheAndEncodingFilter)
• JSP View Resolver + Static Resources (JS/CSS)
• Browser Client
• JavaScript API (epics2web.js) – uses WebSocket or HTTP fetch
• JSP-rendered pages (console.jsp, overview.jsp, test pages)
• CI/CD Infrastructure (optional)
• GitHub Actions for CI (ci.yaml), CD (cd.yaml), dependency updates (dd.yaml)
b. Relationships & Data Flows
1. Browser → HTTP GET → Tomcat → CacheAndEncodingFilter → Controller → JCA ChannelAccess → EPICS PV → Controller → JSP/JSON → Browser
2. Browser → WebSocket handshake → MonitorEndpoint → WebSocketSessionManager → ChannelMonitor (JCA) subscribes to PV → On PV update: ChannelMonitor → MonitorEndpoint → Browser client JS callback
3. Integration Test harness spins up SoftIOC + epics2web services, then uses Java tests to exercise both REST (GetTest.java) and WS (WebSocketTest.java).
c. Architectural Patterns & Principles
• Layered architecture separating transport (HTTP/WebSocket), business logic (ChannelManager), and external system (EPICS network).
• Stateful session management in WebSocketSessionManager vs. stateless REST.
• Reuse of containers for development, testing, and production via Docker Compose.
• Convention-over-configuration for servlet filter and endpoint registration (annotations).
d. Key Technologies & Frameworks
• Java 17 (compiled to Java 8 bytecode), Gradle 7
• EPICS JCA library for Channel Access
• Java WebSocket API (javax.websocket)
• JSP + JSTL for server-side views
• Plain JS client (no heavy frontend framework)
• Docker, Docker Compose for orchestration
• GitHub Actions for CI/CD
Essential Elements
• Clear component names and roles (e.g., “ChannelManager: JCA wrapper”)
• Annotations for environment variables (EPICS_CA_ADDR_LIST, CONTEXT_PREFIX) if space permits