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