# Poco::Data

# class AbstractExtraction

Library: Data
Package: DataCore
Header: Poco/Data/AbstractExtraction.h

## Description

AbstractExtraction is the interface class that connects output positions to concrete values retrieved via an AbstractExtractor.

## Inheritance

Known Derived Classes: BulkExtraction, Extraction

## Member Summary

Member Functions: canExtract, createPreparation, extract, getEmptyStringIsNull, getExtractor, getForceEmptyString, getHeldType, getLimit, isBulk, isNull, isValueNull, numOfColumnsHandled, numOfRowsAllowed, numOfRowsHandled, position, reset, setEmptyStringIsNull, setExtractor, setForceEmptyString, setHeldType, setLimit

## Types Aliases

### ExtractorPtr

using ExtractorPtr = SharedPtr < AbstractExtractor >;

### PreparatorPtr

using PreparatorPtr = SharedPtr < AbstractPreparator >;

### Ptr

using Ptr = SharedPtr < AbstractExtraction >;

## Constructors

### AbstractExtraction

AbstractExtraction(
Poco::UInt32 limit = Limit::LIMIT_UNLIMITED,
Poco::UInt32 position = 0,
bool bulk = false
);

Creates the AbstractExtraction. A limit value equal to EXTRACT_UNLIMITED (0xffffffffu) means that we extract as much data as possible during one execute. Otherwise the limit value is used to partition data extracting to a limited amount of rows.

## Destructor

### ~AbstractExtraction

virtual ~AbstractExtraction();

Destroys the AbstractExtraction.

## Member Functions

### canExtract

virtual bool canExtract() const;

Returns true. Implementations should override it for different behavior.

### createPreparation

virtual AbstractPreparation::Ptr createPreparation(
PreparatorPtr & pPrep,
std::size_t pos
) = 0;

Creates and returns shared pointer to Preparation object for the extracting object.

### extract

virtual std::size_t extract(
std::size_t pos
) = 0;

Extracts a value from the param, starting at the given column position. Returns the number of rows extracted.

### getEmptyStringIsNull

bool getEmptyStringIsNull() const;

Returns the empty string handling flag.

### getExtractor

ExtractorPtr getExtractor() const;

Retrieves the extractor object

### getForceEmptyString

bool getForceEmptyString() const;

Returns the force empty string flag.

### getHeldType

std::string getHeldType() const;

Returns the held type name, if set. If held type name is not set, returns empty string. Held type is optionally set by calling setHeldType<T>() in child classes. Useful for dynamic_cast failure diagnostics.

### getLimit

Poco::UInt32 getLimit() const;

Gets the limit.

### isBulk

bool isBulk() const;

Returns true if this is bulk extraction.

### isNull

virtual bool isNull(
std::size_t row
) const;

In implementations, this function returns true if value at row is null, false otherwise. Normal behavior is to replace nulls with default values. However, extraction implementations may remember the underlying database null values and be able to later provide information about them. Here, this function throws NotImplementedException.

### isValueNull

template < typename T > bool isValueNull(
const T & param67,
bool deflt
);

Utility function to determine the nullness of the value. This generic version always returns default value (i.e. does nothing). The std::string overload does the actual work.

### isValueNull

bool isValueNull(
const std::string & str,
bool deflt
);

Overload for const reference to std::string.

Returns true when folowing conditions are met:

- string is empty - getEmptyStringIsNull() returns true

### isValueNull

bool isValueNull(
const Poco::UTF16String & str,
bool deflt
);

Overload for const reference to UTF16String.

Returns true when folowing conditions are met:

- string is empty - getEmptyStringIsNull() returns true

### numOfColumnsHandled

virtual std::size_t numOfColumnsHandled() const = 0;

Returns the number of columns that the extraction handles.

The trivial case will be one single column but when complex types are used this value can be larger than one.

### numOfRowsAllowed

virtual std::size_t numOfRowsAllowed() const = 0;

Returns the upper limit on number of rows that the extraction will handle.

### numOfRowsHandled

virtual std::size_t numOfRowsHandled() const = 0;

Returns the number of rows that the extraction handles.

The trivial case will be one single row but for collection data types (ie vector) it can be larger.

### position

Poco::UInt32 position() const;

Returns the extraction position.

### reset

virtual void reset();

Resets the extractor so that it can be re-used. Does nothing in this implementation. Implementations should override it for different behavior.

### setEmptyStringIsNull

void setEmptyStringIsNull(
bool emptyStringIsNull
);

Sets the empty string handling flag.

### setExtractor

void setExtractor(
ExtractorPtr pExtractor
);

Sets the class used for extracting the data. Does not take ownership of the pointer.

### setForceEmptyString

void setForceEmptyString(
bool forceEmptyString
);

Sets the force empty string flag.

### setLimit

void setLimit(
Poco::UInt32 limit
);

Sets the limit.

### setHeldType

template < typename T > void setHeldType();