org.neo4j.kernel.impl.query.QuerySubscriber Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of neo4j-kernel Show documentation
Neo4j kernel is a lightweight, embedded Java database designed to store data structured as graphs rather than tables. For more information, see http://neo4j.org.
There is a newer version: 5.25.1
Show newest version
/*
 * Copyright (c) "Neo4j"
 * Neo4j Sweden AB [http://neo4j.com]
 *
 * This file is part of Neo4j.
 *
 * Neo4j is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see .
 */
package org.neo4j.kernel.impl.query;

import org.neo4j.graphdb.QueryStatistics;
import org.neo4j.values.AnyValue;

/**
 * A QuerySubscriber is used for streaming result from a query.
 * 
 * Used in conjunction with a {@link QuerySubscription}. The subscription will demand a number of records, {@link
 * QuerySubscription#request(long)}, and when there is data available the subscriber will receive a call chain like.
 *
 
 *     onResult(3)
 *     onRecord()
 *     onField(0, v1)
 *     onField(1, v2)
 *     onField(2, v3)
 *     onRecordCompleted()
 *     onRecord()
 *     onField(0, v1)
 *     onField(1, v2)
 *     onField(2, v3)
 *     onRecordCompleted()
 *     ...
 *     onResultCompleted(stats)
 * 
 * 
 * Or if some error occurs along the way we will have a call to onError.
 */
public interface QuerySubscriber
{
    /**
     * Called at the beginning of a stream, guaranteed to be called exactly once.
     *
     * @param numberOfFields the number of fields each record of the stream will contain
     */
    void onResult( int numberOfFields ) throws Exception;

    /**
     * Called whenever a new record is ready to be written
     */
    void onRecord() throws Exception;

    /**
     * Writes the field.
     * 
     * This method is guaranteed to be called exactly numberOfFields times with increasing offsets in [0,
     * numberOfFields -1],
     * where numberOfFields is the argument provided in {@link #onResult(int)} ()}
     *
     * @param value the value of the field at the current offset.
     */
    void onField( int offset, AnyValue value ) throws Exception;

    /**
     * The current record has been completed
     */
    void onRecordCompleted() throws Exception;

    /**
     * Called if an error occurs
     *
     * @param throwable the error
     */
    void onError( Throwable throwable ) throws Exception;

    /**
     * Call onError while suppressing any new exception.
     */
    static void safelyOnError( QuerySubscriber subscriber, Throwable t )
    {
        try
        {
            subscriber.onError( t );
        }
        catch ( Exception onErrorException )
        {
            t.addSuppressed( onErrorException );
        }
    }

    /**
     * The result stream is done, no more data to stream.
     *
     * This means that further calls {@link QuerySubscription#request(long)} will not result in more data being
     * streamed to the subscriber.
     * @param statistics The query statistics of the results.
     */
    void onResultCompleted( QueryStatistics statistics );

    /**
     * Dummy implementation that will throw whenever it is being called.
     */
    QuerySubscriber DO_NOTHING_SUBSCRIBER = new QuerySubscriber()
    {
        @Override
        public void onResult( int numberOfFields )
        {

        }

        @Override
        public void onRecord()
        {

        }

        @Override
        public void onField( int offset, AnyValue value )
        {

        }

        @Override
        public void onRecordCompleted()
        {

        }

        @Override
        public void onError( Throwable throwable )
        {

        }

        @Override
        public void onResultCompleted( QueryStatistics statistics )
        {

        }
    };
}