001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.console.views;
018
019import org.apache.juneau.terminal.report.*;
020
021/**
022 * The read side of a terminal-view event stream.
023 *
024 * <p>
025 * Contract: events come back in ascending <c>seq</c>; every page carries a <c>next</c> token; an unknown or stale
026 * token throws {@link UnknownTokenException}; implementations are thread-safe.  There is no tail or before: the
027 * client model needs the events from the start, and an event stream is small next to a log.
028 */
029public interface TerminalViewSource {
030
031   /**
032    * Returns a forward page of events with a <c>seq</c> greater than the token's position.
033    *
034    * @param after The <c>next</c> token of the previous page, or <jk>null</jk> for the start.
035    * @param max The maximum number of events.
036    * @return A forward page.
037    * @throws UnknownTokenException If the token is unknown or stale.
038    */
039   TerminalViewPage page(String after, int max);
040
041   /**
042    * Thrown for an unknown or stale token; endpoints answer <c>410 Gone</c>.
043    */
044   @SuppressWarnings({
045      "java:S9398" // Public API: the exception is part of the TerminalViewSource contract and is referenced as TerminalViewSource.UnknownTokenException.
046   })
047   class UnknownTokenException extends RuntimeException {
048      private static final long serialVersionUID = 1L;
049
050      /**
051       * Constructor.
052       *
053       * @param token The offending token.
054       */
055      public UnknownTokenException(String token) {
056         super("Unknown or stale terminal-view token: '" + TerminalViewChecks.clip(token) + "'.");
057      }
058   }
059}