| 1 | # -*- perl -*- | ||
| 2 | ##---------------------------------------------------------------------------- | ||
| 3 | ## Database Object Interface - ~/lib/DB/Object/Postgres/Lo.pm | ||
| 4 | ## Version v0.301.0 | ||
| 5 | ## Copyright(c) 2024 DEGUEST Pte. Ltd. | ||
| 6 | ## Author: Jacques Deguest <jack@deguest.jp> | ||
| 7 | ## Created 2017/07/19 | ||
| 8 | ## Modified 2026/03/22 | ||
| 9 | ## All rights reserved | ||
| 10 | ## | ||
| 11 | ## This program is free software; you can redistribute it and/or modify it | ||
| 12 | ## under the same terms as Perl itself. | ||
| 13 | ##---------------------------------------------------------------------------- | ||
| 14 | ## Package for PostgreSQL large objects | ||
| 15 | package DB::Object::Postgres::Lo; | ||
| 16 | BEGIN | ||
| 17 | { | ||
| 18 | use strict; | ||
| 19 | use warnings; | ||
| 20 | warnings::register_categories( 'DB::Object' ); | ||
| 21 | use parent qw( Module::Generic ); | ||
| 22 | use vars qw( $VERSION $EXCEPTION_CLASS ); | ||
| 23 | our $EXCEPTION_CLASS = $DB::Object::EXCEPTION_CLASS; | ||
| 24 | our $VERSION = 'v0.301.0'; | ||
| 25 | }; | ||
| 26 | |||
| 27 | use strict; | ||
| 28 | use warnings; | ||
| 29 | |||
| 30 | sub new | ||
| 31 | { | ||
| 32 | my $this = shift( @_ ); | ||
| 33 | my $dbh = shift( @_ ) || return( $this->error( "No database handler was provided." ) ); | ||
| 34 | return( $this->error( "Value provided is not a database handler object." ) ) if( !ref( $dbh ) || ( ref( $dbh ) && !$dbh->isa( 'DB::Object' ) ) ); | ||
| 35 | my $class = ref( $this ) ? ref( $this ) : $this; | ||
| 36 | my $self = {}; | ||
| 37 | $self->{dbh} = $dbh; | ||
| 38 | bless( $self, $class ); | ||
| 39 | $self->{_exception_class} = $EXCEPTION_CLASS; | ||
| 40 | return( $self ); | ||
| 41 | } | ||
| 42 | |||
| 43 | sub close | ||
| 44 | { | ||
| 45 | my $self = shift( @_ ); | ||
| 46 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 47 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 48 | my $rv = $self->{dbh}->pg_lo_close( $fh ); | ||
| 49 | return( $self->error( "Unable to close the large object file descriptor." ) ) if( !defined( $rv ) ); | ||
| 50 | return( $self ); | ||
| 51 | } | ||
| 52 | |||
| 53 | sub create | ||
| 54 | { | ||
| 55 | my $self = shift( @_ ); | ||
| 56 | my $mode = shift( @_ ) || 077; | ||
| 57 | my $id = $self->{dbh}->pg_lo_creat( $mode ); | ||
| 58 | $self->{id} = $id; | ||
| 59 | return( $id ); | ||
| 60 | } | ||
| 61 | |||
| 62 | sub export_file | ||
| 63 | { | ||
| 64 | my $self = shift( @_ ); | ||
| 65 | my $file = shift( @_ ) || return( $self->error( "No file provided to export the large object to." ) ); | ||
| 66 | my $rv = $self->{dbh}->pg_lo_export( $file ); | ||
| 67 | return( $self->error( "Unable to export the large object to file $file." ) ) if( !defined( $rv ) ); | ||
| 68 | return( $self ); | ||
| 69 | } | ||
| 70 | |||
| 71 | sub id | ||
| 72 | { | ||
| 73 | my $self = shift( @_ ); | ||
| 74 | $self->{id} = shift( @_ ) if( @_ ); | ||
| 75 | return( $self->{id} ); | ||
| 76 | } | ||
| 77 | |||
| 78 | sub import_file | ||
| 79 | { | ||
| 80 | my $self = shift( @_ ); | ||
| 81 | my $file = shift( @_ ) || return( $self->error( "No file provided to import the large object from it." ) ); | ||
| 82 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 83 | my $id = $self->{dbh}->pg_lo_import( $file ); | ||
| 84 | return( $self->error( "Unable to import the large object." ) ) if( !defined( $id ) ); | ||
| 85 | my $new = $self->new( $self->{dbh} ); | ||
| 86 | $new->id( $id ); | ||
| 87 | return( $new ); | ||
| 88 | } | ||
| 89 | |||
| 90 | sub import_with_oid | ||
| 91 | { | ||
| 92 | my $self = shift( @_ ); | ||
| 93 | my $file = shift( @_ ) || return( $self->error( "No file provided to import the large object from it." ) ); | ||
| 94 | my $oid = shift( @_ ); | ||
| 95 | return( $self->error( "No oid was provided to import the large object." ) ) if( !defined( $oid ) || !length( $oid ) ); | ||
| 96 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 97 | my $id = $self->{dbh}->pg_lo_import_with_oid( $file, $oid ); | ||
| 98 | return( $self->error( "Unable to import the large object with the oid $oid." ) ) if( !defined( $id ) ); | ||
| 99 | my $new = $self->new( $self->{dbh} ); | ||
| 100 | $new->id( $id ); | ||
| 101 | return( $new ); | ||
| 102 | } | ||
| 103 | |||
| 104 | sub open | ||
| 105 | { | ||
| 106 | my $self = shift( @_ ); | ||
| 107 | my $id = shift( @_ ); | ||
| 108 | return( $self->error( "No id was provided." ) ) if( !defined( $id ) || !length( $id ) ); | ||
| 109 | ## $dbh->{pg_INV_READ}, $dbh->{pg_INV_WRITE}, $dbh->{pg_INV_READ} | $dbh->{pg_INV_WRITE} | ||
| 110 | my $mode = shift( @_ ); | ||
| 111 | my $fh = $self->{dbh}->pg_lo_open( $id, $mode ); | ||
| 112 | return( $self->error( "Cannot open large object. An error has occured." ) ) if( !defined( $fh ) ); | ||
| 113 | $self->{fh} = $fh; | ||
| 114 | return( $self ); | ||
| 115 | } | ||
| 116 | |||
| 117 | sub read | ||
| 118 | { | ||
| 119 | my $self = shift( @_ ); | ||
| 120 | my( $buffer, $len ) = @_; | ||
| 121 | return( $self->error( "No length was provided." ) ) if( !defined( $len ) || !length( $len ) ); | ||
| 122 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 123 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 124 | my $bytes = $self->{dbh}->pg_lo_read( $fh, $buffer, $len ); | ||
| 125 | return( $self->error( "Unable to read from the large object file descriptor." ) ) if( !defined( $bytes ) ); | ||
| 126 | return( $bytes ); | ||
| 127 | } | ||
| 128 | |||
| 129 | sub seek | ||
| 130 | { | ||
| 131 | my $self = shift( @_ ); | ||
| 132 | my( $offset, $whence ) = @_; | ||
| 133 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 134 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 135 | my $loc = $self->{dbh}->pg_lo_lseek( $fh, $offset, $whence ); | ||
| 136 | return( $self->error( "Unable to seek a position from the large object file descriptor." ) ) if( !defined( $loc ) ); | ||
| 137 | return( $loc ); | ||
| 138 | } | ||
| 139 | |||
| 140 | sub tell | ||
| 141 | { | ||
| 142 | my $self = shift( @_ ); | ||
| 143 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 144 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 145 | my $loc = $self->{dbh}->pg_lo_tell( $fh ); | ||
| 146 | return( $self->error( "Unable to get the current position from the large object file descriptor." ) ) if( !defined( $loc ) ); | ||
| 147 | return( $loc ); | ||
| 148 | } | ||
| 149 | |||
| 150 | sub truncate | ||
| 151 | { | ||
| 152 | my $self = shift( @_ ); | ||
| 153 | my $len = shift( @_ ); | ||
| 154 | return( $self->error( "No length was provided." ) ) if( !defined( $len ) || !length( $len ) ); | ||
| 155 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 156 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 157 | my $rv = $self->{dbh}->pg_lo_truncate( $fh ); | ||
| 158 | return( $self->error( "Unable to truncate the large object file descriptor." ) ) if( !defined( $rv ) ); | ||
| 159 | return( $self ); | ||
| 160 | } | ||
| 161 | |||
| 162 | sub unlink | ||
| 163 | { | ||
| 164 | my $self = shift( @_ ); | ||
| 165 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 166 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 167 | my $rv = $self->{dbh}->pg_lo_unlink( $fh ); | ||
| 168 | return( $self->error( "Unable to delete the large object file descriptor." ) ) if( !defined( $rv ) ); | ||
| 169 | return( $self ); | ||
| 170 | } | ||
| 171 | |||
| 172 | sub write | ||
| 173 | { | ||
| 174 | my $self = shift( @_ ); | ||
| 175 | my( $buffer, $len ) = @_; | ||
| 176 | return( $self->error( "No length was provided." ) ) if( !defined( $len ) || !length( $len ) ); | ||
| 177 | return( $self->error( "Deactivate AutoCommit before using this function." ) ) if( $self->{dbh}->{AutoCommit} ); | ||
| 178 | my $fh = $self->{fh} || return( $self->error( "No file handle currently set. You must open the large object before using this method." ) ); | ||
| 179 | my $bytes = $self->{dbh}->pg_lo_write( $fh, $buffer, $len ); | ||
| 180 | return( $self->error( "Unable to write to the large object file descriptor." ) ) if( !defined( $bytes ) ); | ||
| 181 | return( $bytes ); | ||
| 182 | } | ||
| 183 | |||
| 184 | 1; | ||
| 185 | |||
| 186 | # NOTE: POD | ||
| 187 | __END__ |