DequeueResult.hpp

// Copyright (c) 2004-2023 TIBCO Software Inc.  All rights reserved.

#ifndef DEQUEUE_RESULT_H
#define DEQUEUE_RESULT_H

#include "StreamBase.hpp"

#include "StreamProperties.hpp"
#include "Tuple.hpp"
#include "TupleList.hpp"
#include "StreamBaseURI.hpp"
#include "StreamBaseConstants.hpp"

SB_INTERNAL_FWD(DequeueResultUtil);

SB_NAMESPACE_BEGIN;

/// Null value encountered
STREAMBASE_EXCEPTION_TYPE(ArgumentOutOfRange, sb_internal::Errors::NON_FATAL_ERROR);

/// Encapsulates the data returned from a dequeue() operation.
/// Contains a stream name and a list of tuples.
class DequeueResult {
public:
#ifndef SWIG    // not supported by SWIG, and not especially useful in scripting languages anyway
    ///
    /// A callback interface that can be implemented by an object that is associated with 
    /// a StreamBaseClient and which gets used in the course of dequeuing tuples.
    ///
    class Interceptor {
      public:
        /// SUPPRESSED is a flag used to signify that the results from processResult should
        /// be suppressed.
        static const DequeueResult SUPPRESSED;

        virtual ~Interceptor() {}
        ///
        /// Take a DequeueResult and modify it. Returns the same object if
        /// there are no changes. Returns SUPPRESSED if results should 
        ///  be suppressed. 
        /// May return a different DequeueResult object.
        ///
        virtual DequeueResult processResult(const DequeueResult &results) {
            // do nothing
            return results;
        }
    };
#endif

    /// Possible Dequeue results status 
    enum Status {
        UNINITIALIZED = 0,
        GOOD = 1,
        TIMEOUT = 2,
        CLOSED = 3,
    };

    /// Default (null) Constructor
    DequeueResult() : _status(UNINITIALIZED), _leadershipStatus(LEADER) {};

    /// Create a Dequeue Result with a list of tuples, with the given LeadershipStatus
    DequeueResult(const StreamProperties &props, 
                  const TupleList& tuples, 
                  const StreamBaseURI &serverURI, 
                  LeadershipStatus _leadershipStatus);

    virtual ~DequeueResult();

    /// Currently a no-op maintained for backwards compatibility
    /// @deprecated
    void reuseTuple() { }

    /// Return the status of this DequeueResult.
    /// DequeueResult::GOOD means the DequeueResult contains tuples.
    /// @return the status of this DequeueResult
    const DequeueResult::Status getStatus() const;

    /// Returns the name of the stream on which tuples were dequeued.
    const std::string& getStreamName() const;

    /// Returns the number of tuples dequeued.
    int getTupleCount() const;

    /// Returns the StreamProperties for this DequeueResult
    const StreamProperties& getStreamProperties() const;

    /// Returns the index'th tuple.
    const Tuple& getTuple(int index) const;

    /// Returns the list of tuples
    const TupleList& getTuples() const;

    /// Return the leadership status of the server that produced this dequeue result.
    LeadershipStatus getLeadershipStatus() const {
        return _leadershipStatus;
    }

    /// return the server that produced these results
    const StreamBaseURI &getServerURI() const {
        return _serverURI;
    }
private:
    /// create a DequeueResult with the given DequeueResult status and LeadershipStatus
    DequeueResult(DequeueResult::Status status, LeadershipStatus leadershipStatus);

    friend class sb_internal::DequeueResultUtil;

    TupleList _tuples;
    StreamProperties _props;
    bool _isLogicalControlStreamMessage;
    DequeueResult::Status _status;
    LeadershipStatus _leadershipStatus;
    StreamBaseURI _serverURI;
};

SB_NAMESPACE_END;
#endif