src/components/devtools_bridge/android/java/src/org/chromium/components/devtools_bridge/AbstractDataChannel.java

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 package org.chromium.components.devtools_bridge;
   6
   7 import java.nio.ByteBuffer;
   8
   9 /**
  10  * Limited view on org.webrtc.DataChannel. Abstraction layer helps with:
  11  * 1. Mocking in tests. There is no need to emulate full set of features of the DataChannel.
  12  * 2. Allows both native and Java API implementation for WebRTC data channel.
  13  * 3. Hides unused features.
  14  * Only SCTP data channels supported.
  15  * Data channel is thread safe (except the dispose method).
  16  */
  17 public abstract class AbstractDataChannel {
  18     /**
  19      *  Observer's callbacks are called on WebRTC signaling thread (or it's equivalent in tests).
  20      */
  21     public interface Observer {
  22         void onStateChange(State state);
  23
  24         /**
  25          * TEXT and BINARY messages should be handled equally. Size of the message is
  26          * |message|.remaining(). |message| may reference to a native buffer on stack so
  27          * the reference to the buffer must not outlive the invocation.
  28          */
  29         void onMessage(ByteBuffer message);
  30     }
  31
  32     /**
  33      * Type is only significant for JavaScript-based counterpart. TEXT messages will
  34      * be observed as strings, BINARY as ByteArray's.
  35      */
  36     public enum MessageType {
  37         TEXT, BINARY
  38     }
  39
  40     /**
  41      * State of the data channel.
  42      * Only 2 states of channel are important here: OPEN and everything else.
  43      */
  44     public enum State {
  45         OPEN, CLOSED
  46     }
  47
  48     /**
  49      * Registers an observer.
  50      */
  51     public abstract void registerObserver(Observer observer);
  52
  53     /**
  54      * Unregisters the previously registered observer.
  55      * Observer unregistration synchronized with signaling thread. If some data modified
  56      * in observer callbacks without additional synchronization it's safe to access
  57      * this data on the current thread after calling this method.
  58      */
  59     public abstract void unregisterObserver();
  60
  61     /**
  62      * Sending message to the data channel.
  63      * Message size is |message|.remaining().
  64      */
  65     public abstract void send(ByteBuffer message, MessageType type);
  66
  67     /**
  68      * Closing data channel. Both channels in the pair will change state to CLOSED.
  69      */
  70     public abstract void close();
  71
  72     /**
  73      * Releases native objects (if any). Closes data channel. No other methods are allowed after it
  74      * (in multithread scenario needs synchronization with access to the data channel).
  75      */
  76     public abstract void dispose();
  77 }