view release on metacpan or  search on metacpan

lib/Database/BI/Model/DataSource.pm  view on Meta::CPAN

=head2 source_url

Returns the source URL for URL/HTML-table-backed instances.
Returns C<undef> for all file-backed instances (local files and SFTP-fetched
remote files).

Use this to distinguish a URL-backed C<DataSource> from a file-backed one
when you need to decide whether to show a "re-fetch" button to the user.

=head3 API SPECIFICATION

=head4 INPUT

None.

=head4 OUTPUT

    SCALAR string    # 'https://example.com/data.html' -- the original URL
    undef            # file-backed (local or SFTP) sources

=head3 MESSAGES

None.

=cut

sub source_url {
	my $self = shift;
	return $self->{_url};
}

=head2 updated

Returns the Unix epoch timestamp (mtime) of the backing data file, or
C<undef> for URL-backed tables and for sources whose file cannot be
C<stat()>-ed.

C<Database::Join> calls C<updated()> on each component database to
detect whether its SQLite spill cache is stale.  When a source file changes
on disk, the mtime increases, the join detects the change, and re-runs the
join rather than serving stale cached data.

=head3 API SPECIFICATION

=head4 INPUT

None.

=head4 OUTPUT

    SCALAR integer   # Unix epoch seconds, e.g. 1728601234
    undef            # URL-backed tables, or file cannot be stat()-ed

=head3 MESSAGES

None.

=cut

sub updated {
	my $self = shift;
	# Delegate to the D::A backend when available -- it tracks mtime internally.
	return $self->{_db}->updated() if $self->{_db} && $self->{_db}->can('updated');
	# Fallback: stat the file path directly (header-less CSV and XLSX bypass D::A).
	return (stat($self->{_file_path}))[9] if defined $self->{_file_path} && -f $self->{_file_path};
	return undef;
}

# ---------------------------------------------------------------------------
# Public data-access methods
# ---------------------------------------------------------------------------

=head1 METHODS

=head2 fetch_all

Returns every record in the table as an arrayref of hashrefs (one hashref
per row; keys are the column names).

This is the primary data-retrieval method.  It is equivalent to calling
C<selectall_arrayref> with no arguments and normalising the result to an
arrayref.  Prefer C<selectall_arrayref> when passing to C<Database::Join>
(it is the method that C<Database::Join> calls internally).

Filtering (C<eq>, C<contains>, C<gt>, C<lt>, etc.) is applied at the
controller layer by C<Dashboard::_apply_filter_spec> after C<fetch_all>
returns.  C<DataSource> itself is filter-unaware.

Three fast-path shortcuts are checked before touching the DBI backend,
in this order:

=over 4

=item 1.

C<_file_is_empty> is set (0-byte or blank-first-line file) -- returns C<[]>
immediately, no DBI connection.

=item 2.

C<_file_data> is set (pre-parsed header-less CSV, XLSX, or BerkeleyDB data) --
returns the in-memory arrayref directly.

=item 3.

A matching CHI cache entry exists -- returns the cached arrayref without
calling C<Database::Abstraction>.

=back

=head3 API SPECIFICATION

=head4 INPUT

None.  Filtering is applied at the controller layer, not inside C<DataSource>.

=head4 OUTPUT

    ARRAYREF of HASHREF   # one hashref per row; keys are column names
    []                    # empty arrayref when the file is empty or has no data rows