1 /*

     2  * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package jdk.jfr.consumer;

    27 

    28 import java.io.IOException;

    29 import java.nio.file.Path;

    30 import java.time.Duration;

    31 import java.util.function.Consumer;

    32 

    33 /**

    34  * Represents a stream of event that actions can be performed up on.

    35  */

    36 public interface EventStream extends AutoCloseable {

    37 

    38     /**

    39      * Creates a stream starting from the next written event in a disk

    40      * repository.

    41      *

    42      * @param directory location of the disk repository, not {@code null}

    43      * @return an event stream, not {@code null}

    44      */

    45     public static EventStream openRepository(Path directory) throws IOException {

    46         throw new UnsupportedOperationException("Not yet implemented");

    47 //       AccessControlContext acc = AccessController.getContext();

    48 //       return new EventDirectoryStream(acc);

    49     }

    50 

    51     /**

    52      * Creates an event stream starting from the first event in a file.

    53      *

    54      * @param file location of the file, not {@code null}

    55      * @return an event stream, not {@code null}

    56      */

    57     public static EventStream openFile(Path file) throws IOException {

    58         throw new UnsupportedOperationException("Not yet implemented");

    59 //      return new EventFileStream(file);

    60     }

    61 

    62     /**

    63      * Performs an action on all events in the stream.

    64      *

    65      * @param action an action to be performed on each {@code RecordedEvent},

    66      *        not {@code null}

    67      */

    68     void onEvent(Consumer<RecordedEvent> action);

    69 

    70     /**

    71      * Performs an action on all events in the stream with a specified name.

    72      *

    73      * @param eventName the name of the event, not {@code null}

    74      * @param action an action to be performed on each {@code RecordedEvent}

    75      *        that matches the event name, not {@code null}

    76      */

    77     void onEvent(String eventName, Consumer<RecordedEvent> action);

    78 

    79     /**

    80      * Performs an action when the event stream has been flushed.

    81      *

    82      * @param action an action to be performed after stream has been flushed,

    83      *        not {@code null}

    84      */

    85     void onFlush(Runnable action);

    86 

    87     /**

    88      * Performs an action when the event stream is closed.

    89      *

    90      * @param action an action to be performed after the stream has been closed,

    91      *        not {@code null}

    92      */

    93     void onClose(Runnable action);

    94 

    95     /**

    96      * Releases all resources associated with this event stream.

    97      */

    98     void close();

    99 

   100     /**

   101      * Removes an action from the stream.

   102      * <p>

   103      * If the action has been added multiple times, all instance of it will be

   104      * removed.

   105      *

   106      * @param action the action to remove, not {@code null}

   107      * @return {@code true} if the action was removed, {@code false} otherwise

   108      *

   109      * @see #onClose(Runnable)

   110      * @see #onFlush(Runnable)

   111      * @see #onEvent(Consumer)

   112      * @see #onEvent(String, Consumer)

   113      */

   114     boolean remove(Object action);

   115 

   116     /**

   117      * Starts processing events in the stream.

   118      * <p>

   119      * All actions will performed on this stream will happen in the current

   120      * thread.

   121      *

   122      * @throws IllegalStateException if the stream is already started or if it

   123      *         has been closed

   124      */

   125     void start();

   126 

   127     /**

   128      * Starts processing events in the stream asynchronously.

   129      * <p>

   130      * All actions on this stream will be performed in a separate thread.

   131      *

   132      * @throws IllegalStateException if the stream is already started or if it

   133      *         has been closed

   134      */

   135     void startAsync();

   136 

   137     /**

   138      * Blocks the current thread until the stream is finished, closed, or it

   139      * times out.

   140      *

   141      * @param timeout the maximum time to wait, not {@code null}

   142      *

   143      * @see #start()

   144      * @see #startAsync()

   145      */

   146     void awaitTermination(Duration timeout);

   147 

   148     /**

   149      * Blocks the current thread until the stream is finished or closed.

   150      *

   151      * @see #start()

   152      * @see #startAsync()

   153      */

   154     void awaitTermination();

   155 }