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.bus;
018
019import java.util.*;
020
021/**
022 * One page's bridge session.  Created by the session POST; reused across reconnects within the grace period.
023 *
024 * <p>
025 * The session's capability id is deliberately not on this interface: it never leaves the bus module except in the
026 * session POST response, and {@code toString()} redacts it.
027 *
028 * <h5 class='section'>Example:</h5>
029 * <p class='bjava'>
030 *   <jv>bus</jv>.publishTo(<jv>s</jv> -&gt; <js>"east"</js>.equals(<jv>s</jv>.attribute(<js>"region"</js>)), <js>"ops.alert:east"</js>, <jv>alert</jv>);
031 * </p>
032 *
033 * @since 10.0.0
034 */
035public interface BusSession {
036
037   /**
038    * The bridge id from the page contract (C1 id pattern).
039    *
040    * @return The bridge id.  Never <jk>null</jk>.
041    */
042   String bridgeId();
043
044   /**
045    * The transport requested by the session POST.
046    *
047    * @return {@code "sse"} or {@code "websocket"}.
048    */
049   String transport();
050
051   /**
052    * The name of the request principal recorded when the session was opened.
053    *
054    * @return The principal name, or <jk>null</jk> when the request was anonymous.
055    */
056   String principalName();
057
058   /**
059    * A value captured by {@link BusPolicy.Builder#sessionAttributes(java.util.function.Function)} at session open.
060    *
061    * @param name The attribute name.
062    * @return The value, or <jk>null</jk> if absent.
063    */
064   Object attribute(String name);
065
066   /**
067    * The downstream topics and patterns this session was granted, in request order.
068    *
069    * @return An unmodifiable set.
070    */
071   Set<String> downstream();
072
073   /**
074    * The upstream topics this session was granted (WebSocket sessions only), in request order.
075    *
076    * @return An unmodifiable set.
077    */
078   Set<String> upstream();
079
080   /**
081    * Whether a transport connection is currently attached.
082    *
083    * @return <jk>true</jk> while a stream or socket is connected.
084    */
085   boolean isConnected();
086}