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 java.io.*;
020import java.util.*;
021
022import org.apache.juneau.http.*;
023import org.apache.juneau.marshall.json.*;
024import org.apache.juneau.rest.server.*;
025
026/**
027 * Mixin interface that serves the terminal-view events endpoint.
028 *
029 * <p>
030 * The one abstract method is the application's resolver, which is where authorization lives: an unknown id and a
031 * forbidden id both answer {@code 404}, so ids cannot be enumerated.  Run ids are opaque URL tokens matching
032 * {@code ^[A-Za-z0-9_-]{1,128}$}; anything else answers {@code 400} before the resolver runs.
033 *
034 * <h5 class='section'>Example:</h5>
035 * <p class='bjava'>
036 *    <ja>@Rest</ja>
037 *    <jk>public class</jk> RunsResource <jk>extends</jk> BasicRestServlet <jk>implements</jk> TerminalViewMixin {
038 *       <ja>@Override</ja>
039 *       <jk>public</jk> Optional&lt;TerminalViewSource&gt; terminalViewSource(String <jv>runId</jv>, RestRequest <jv>req</jv>) {
040 *          <jk>return</jk> <jf>runs</jf>.find(<jv>runId</jv>).map(Run::events);
041 *       }
042 *    }
043 * </p>
044 */
045public interface TerminalViewMixin {
046
047   /** The URL path prefix for the terminal-view endpoint (relative to the host mount). */
048   String RUN_VIEW_PREFIX = "/juneau-terminal-view";
049
050   /** The URL path template of the events endpoint. */
051   String EVENTS_PATH = RUN_VIEW_PREFIX + "/{runId}/events";
052
053   /**
054    * Resolves the source for a run id, applying the application's own access rules.
055    *
056    * @param runId The run id from the URL path (already checked against the grammar).
057    * @param req The in-flight request.
058    * @return The source, or empty when the id is unknown or the caller may not read it.
059    */
060   Optional<TerminalViewSource> terminalViewSource(String runId, RestRequest req);
061
062   /**
063    * [GET /juneau-terminal-view/{runId}/events] &mdash; one page of events as JSON.
064    *
065    * @param runId The run id.
066    * @param req The request.
067    * @param res The response.
068    * @throws IOException If the response could not be written.
069    */
070   @RestGet(path=EVENTS_PATH, summary="Terminal view events", serializers=JsonSerializer.class, swagger=@OpSwagger(ignore=true))
071   default void terminalViewEvents(@Path("runId") String runId, RestRequest req, RestResponse res) throws IOException {
072      TerminalViewEndpoints.events(terminalViewSource(TerminalViewEndpoints.checkRunId(runId), req), req, res);
073   }
074}