projekt kivitendo

  $::request->layout->use_javascript("${_}.js") for qw(jquery.selectboxes jquery.multiselect2side kivi.File);

# This file has been auto-generated only because it didn't exist.

# Feel free to modify it at will; it will not be overwritten automatically.

package SL::DB::File;

use strict;

use SL::DB::MetaSetup::File;

use SL::DB::Manager::File;

__PACKAGE__->meta->initialize;

1;

__END__

=pod

=encoding utf8

=head1 NAME

  SL::DB::File - Databaseclass for File

=head1 SYNOPSIS

  use SL::DB::File;

  # synopsis...

=head1 DESCRIPTION

  # longer description.

=head1 INTERFACE

=head1 DEPENDENCIES

=head1 SEE ALSO

=head1 AUTHOR

  Werner Hahn E<lt>wh@futureworldsearch.netE<gt>

=cut

use SL::DB::File;

  files                          => 'file',

# This file has been auto-generated only because it didn't exist.

# Feel free to modify it at will; it will not be overwritten automatically.

package SL::DB::Manager::File;

use strict;

use parent qw(SL::DB::Helper::Manager);

use SL::DB::Helper::Sorted;

sub object_class { 'SL::DB::File' }

__PACKAGE__->make_manager_methods;

1;

  doc_database                              => { type => 'boolean', default => 'false' },

  doc_delete_printfiles                     => { type => 'boolean', default => 'false' },

  doc_files                                 => { type => 'boolean', default => 'false' },

  doc_files_rootpath                        => { type => 'text', default => '' },

  doc_max_filesize                          => { type => 'integer', default => 1000000 },

  doc_storage                               => { type => 'boolean', default => 'false' },

  doc_storage_for_attachments               => { type => 'text', default => 'Filesystem' },

  doc_storage_for_documents                 => { type => 'text', default => 'Filesystem' },

  doc_storage_for_images                    => { type => 'text', default => 'Filesystem' },

  doc_webdav                                => { type => 'boolean', default => 'false' },

# This file has been auto-generated. Do not modify it; it will be overwritten

# by rose_auto_create_model.pl automatically.

package SL::DB::File;

use strict;

use parent qw(SL::DB::Object);

__PACKAGE__->meta->table('files');

__PACKAGE__->meta->columns(

  backend      => { type => 'text' },

  backend_data => { type => 'text' },

  description  => { type => 'text' },

  file_name    => { type => 'text', not_null => 1 },

  file_type    => { type => 'text', not_null => 1 },

  id           => { type => 'serial', not_null => 1 },

  itime        => { type => 'timestamp', default => 'now()' },

  mime_type    => { type => 'text', not_null => 1 },

  mtime        => { type => 'timestamp' },

  object_id    => { type => 'integer', not_null => 1 },

  object_type  => { type => 'text', not_null => 1 },

  source       => { type => 'text', not_null => 1 },

  title        => { type => 'varchar', length => 45 },

);

__PACKAGE__->meta->primary_key_columns([ 'id' ]);

__PACKAGE__->meta->allow_inline_column_values(1);

1;

;

package SL::Dev::File;

use strict;

use base qw(Exporter);

our @EXPORT = qw(create_scanned create_uploaded create_created get_all_count get_all get_all_versions delete_all);

use SL::DB::File;

sub create_scanned {

  my (%params) = @_;

  $params{source}    = 'scanner1';

  $params{file_type} = 'document';

  $params{file_path} = '/var/tmp/'.$params{file_name} if !$params{file_path};

  open(OUT,"> ".$params{file_path});

  print OUT $params{file_contents};

  close(OUT);

  delete $params{file_contents};

  my $file = _create_file(%params);

  unlink($params{file_path});

  return $file;

}

sub create_uploaded {

  my (%params) = @_;

  $params{source}    = 'uploaded';

  $params{file_type} = 'attachment';

  return _create_file(%params);

}

sub create_created {

  my (%params) = @_;

  $params{source}    = 'created';

  $params{file_type} = 'document';

  return _create_file(%params);

}

sub _create_file {

  my (%params) = @_;

  my $fileobj = SL::File->save(

    object_id          => 1,

    object_type        => 'sales_order',

    mime_type          => 'text/plain',

    description        => 'Test File',

    file_type          => $params{file_type},

    source             => $params{source},

    file_name          => $params{file_name},

    file_contents      => $params{file_contents},

    file_path          => $params{file_path}

  );

  return $fileobj;

}

sub get_all_count {

  my ($class,%params) = @_;

  $params{object_id}   = 1;

  $params{object_type} = 'sales_order';

  return SL::File->get_all_count(%params);

}

sub get_all {

  my ($class,%params) = @_;

  $params{object_id}   = 1;

  $params{object_type} = 'sales_order';

  SL::File->get_all(%params);

}

sub get_all_versions {

  my ($class,%params) = @_;

  $params{object_id}   = 1;

  $params{object_type} = 'sales_order';

  SL::File->get_all_versions(%params);

}

sub delete_all {

  my ($class,%params) = @_;

  $params{object_id}   = 1;

  $params{object_type} = 'sales_order';

  SL::File->delete_all(%params);

}

1;

__END__

=head1 NAME

SL::Dev::File - create file objects for testing, with minimal defaults

=head1 FUNCTIONS

=head2 C<create_scanned %PARAMS>

=head2 C<create_uploaded %PARAMS>

=head2 C<create_created %PARAMS>

=head2 C<delete_all>

=head1 AUTHOR

Martin Helmling E<lt>martin.helmling@opendynamic.deE<gt>

=cut

package SL::File;

use strict;

use parent qw(Rose::Object);

use Clone qw(clone);

use SL::File::Backend;

use SL::File::Object;

use SL::DB::History;

use SL::DB::File;

use SL::Helper::UserPreferences;

use SL::JSON;

use constant RENAME_OK          => 0;

use constant RENAME_EXISTS      => 1;

use constant RENAME_NOFILE      => 2;

use constant RENAME_SAME        => 3;

use constant RENAME_NEW_VERSION => 4;

sub get {

  my ($self, %params) = @_;

  die 'no id' unless $params{id};

  my $dbfile = SL::DB::Manager::File->get_first(query => [id => $params{id}]);

  die 'not found' unless $dbfile;

  $main::lxdebug->message(LXDebug->DEBUG2(), "object_id=".$dbfile->object_id." object_type=".$dbfile->object_type." dbfile=".$dbfile);

  SL::File::Object->new(db_file => $dbfile, id => $dbfile->id, loaded => 1);

}

sub get_version_count {

  my ($self, %params) = @_;

  die "no id or dbfile" unless $params{id} || $params{dbfile};

  $params{dbfile} = SL::DB::Manager::File->get_first(query => [id => $params{id}]) if !$params{dbfile};

  die 'not found' unless $params{dbfile};

  my $backend = $self->_get_backend($params{dbfile}->backend);

  return $backend->get_version_count(%params);

}

sub get_all {

  my ($self, %params) = @_;

  my @files;

  return @files unless $params{object_type};

  return @files unless defined($params{object_id});

  my @query = (

    object_id   => $params{object_id},

    object_type => $params{object_type}

  );

  push @query, (file_name => $params{file_name}) if $params{file_name};

  push @query, (file_type => $params{file_type}) if $params{file_type};

  push @query, (mime_type => $params{mime_type}) if $params{mime_type};

  push @query, (source    => $params{source})    if $params{source};

  my $sortby = $params{sort_by} || 'itime DESC,file_name ASC';

  @files = @{ SL::DB::Manager::File->get_all(query => [@query], sort_by => $sortby) };

  map { SL::File::Object->new(db_file => $_, id => $_->id, loaded => 1) } @files;

}

sub get_all_versions {

  my ($self, %params) = @_;

  my @versionobjs;

  my @fileobjs = $self->get_all(%params);

  if ( $params{dbfile} ) {

    push @fileobjs, SL::File::Object->new(dbfile => $params{db_file}, id => $params{dbfile}->id, loaded => 1);

  } else {

    @fileobjs = $self->get_all(%params);

  }

  foreach my $fileobj (@fileobjs) {

    $main::lxdebug->message(LXDebug->DEBUG2(), "obj=" . $fileobj . " id=" . $fileobj->id." versions=".$fileobj->version_count);

    my $maxversion = $fileobj->version_count;

    push @versionobjs, $fileobj;

    if ($maxversion > 1) {

      for my $version (2..$maxversion) {

        $main::lxdebug->message(LXDebug->DEBUG2(), "clone for version=".($maxversion-$version+1));

        eval {

          my $clone = clone($fileobj);

          $clone->version($maxversion-$version+1);

          $clone->newest(0);

          $main::lxdebug->message(LXDebug->DEBUG2(), "clone version=".$clone->version." mtime=". $clone->mtime);

          push @versionobjs, $clone;

          1;

        }

      }

    }

  }

  return @versionobjs;

}

sub get_all_count {

  my ($self, %params) = @_;

  return 0 unless $params{object_type};

  my @query = (

    object_id   => $params{object_id},

    object_type => $params{object_type}

  );

  push @query, (file_name => $params{file_name}) if $params{file_name};

  push @query, (file_type => $params{file_type}) if $params{file_type};

  push @query, (mime_type => $params{mime_type}) if $params{mime_type};

  push @query, (source    => $params{source})    if $params{source};

  my $cnt = SL::DB::Manager::File->get_all_count(query => [@query]);

  return $cnt;

}

sub delete_all {

  my ($self, %params) = @_;

  return 0 unless defined($params{object_id}) || $params{object_type};

  my $files = SL::DB::Manager::File->get_all(

    query => [

      object_id   => $params{object_id},

      object_type => $params{object_type}

    ]

  );

  foreach my $file (@{$files}) {

    $params{dbfile} = $file;

    $self->delete(%params);

  }

}

sub delete {

  my ($self, %params) = @_;

  die "no id or dbfile" unless $params{id} || $params{dbfile};

  my $rc = SL::DB->client->with_transaction(\&_delete, $self, %params);

  if (!$rc) {

    my $err = SL::DB->client->error;

    die (ref $err?$$err:$err);

  }

  return $rc;

}

sub _delete {

  my ($self, %params) = @_;

  $params{dbfile} = SL::DB::Manager::File->get_first(query => [id => $params{id}]) if !$params{dbfile};

  my $backend = $self->_get_backend($params{dbfile}->backend);

  if ( $params{dbfile}->file_type eq 'document' && $params{dbfile}->source ne 'created')

  {

    ## must unimport

    my $hist = SL::DB::Manager::History->get_first(

      where => [

        addition  => 'IMPORT',

        trans_id  => $params{dbfile}->object_id,

        what_done => $params{dbfile}->id

      ]

    );

    if ($hist) {

      if (!$main::auth->assert('import_ar | import_ap', 1)) {

        die \'no permission to unimport';

      }

      my $file = $backend->get_filepath(dbfile => $params{dbfile});

      $main::lxdebug->message(LXDebug->DEBUG2(), "del file=" . $file . " to=" . $hist->snumbers);

      File::Copy::copy($file, $hist->snumbers) if $file;

      $hist->addition('UNIMPORT');

      $hist->save;

    }

  }

  if ($backend->delete(%params)) {

    my $do_delete = 0;

    if ( $params{last} || $params{all_but_notlast} ) {

      if ( $backend->get_version_count > 0 ) {

        $params{dbfile}->mtime(DateTime->now_local);

        $params{dbfile}->save;

      } else {

        $do_delete = 1;

      }

    } else {

      $do_delete = 1;

    }

    $params{dbfile}->delete if $do_delete;

    return 1;

  }

  return 0;

}

sub save {

  my ($self, %params) = @_;

  my $obj = SL::DB->client->with_transaction(\&_save, $self, %params);

  if (!$obj) {

    my $err = SL::DB->client->error;

    die (ref $err?$$err:$err);

  }

  return $obj;

}

sub _save {

  my ($self, %params) = @_;

  my $file = $params{dbfile};

  my $exists = 0;

  if ($params{id}) {

    $file = SL::DB::File->new(id => $params{id})->load;

    die \'dbfile not exists'     unless $file;

  } elsif (!$file) {

  $main::lxdebug->message(LXDebug->DEBUG2(), "obj_id=" .$params{object_id});

    die \'no object type set'    unless $params{object_type};

    die \'no object id set'      unless defined($params{object_id});

    $exists = $self->get_all_count(%params);

    die 'filename still exist' if $exists && $params{fail_if_exists};

    if ($exists) {

      my ($obj1) = $self->get_all(%params);

      $file = $obj1->db_file;

    } else {

      $file = SL::DB::File->new();

      $file->assign_attributes(

        object_id      => $params{object_id},

        object_type    => $params{object_type},

        source         => $params{source},

        file_type      => $params{file_type},

        file_name      => $params{file_name},

        mime_type      => $params{mime_type},

        title          => $params{title},

        description    => $params{description},

      );

    }

  } else {

    $exists = 1;

  }

  if ($exists) {

    #change attr on existing file

    $file->file_name  ($params{file_name})   if $params{file_name};

    $file->mime_type  ($params{mime_type})   if $params{mime_type};

    $file->title      ($params{title})       if $params{title};

    $file->description($params{description}) if $params{description};

  }

  if ( !$file->backend ) {

    $file->backend($self->_get_backend_by_file_type($file));

    # load itime for new file

    $file->save->load;

  }

  $main::lxdebug->message(LXDebug->DEBUG2(), "backend3=" .$file->backend);

  my $backend = $self->_get_backend($file->backend);

  $params{dbfile} = $file;

  $backend->save(%params);

  $file->mtime(DateTime->now_local);

  $file->save;

  if ($params{file_type} eq 'document' && $params{source} ne 'created') {

    SL::DB::History->new(

      addition    => 'IMPORT',

      trans_id    => $params{object_id},

      snumbers    => $params{file_path},

      employee_id => SL::DB::Manager::Employee->current->id,

      what_done   => $params{dbfile}->id

    )->save();

  }

  return $params{obj} if $params{dbfile} && $params{obj};

  return SL::File::Object->new(db_file => $file, id => $file->id, loaded => 1);

}

sub rename {

  my ($self, %params) = @_;

  return RENAME_NOFILE unless $params{id} || $params{dbfile};

  my $file = $params{dbfile};

  $file = SL::DB::Manager::File->get_first(query => [id => $params{id}]) if !$file;

  return RENAME_NOFILE unless $file;

  $main::lxdebug->message(LXDebug->DEBUG2(), "rename id=" . $file->id . " to=" . $params{to});

  if ($params{to}) {

    return RENAME_SAME   if $params{to} eq $file->file_name;

    return RENAME_EXISTS if $self->get_all_count( object_id     => $file->object_id,

                                                  object_type   => $file->object_type,

                                                  mime_type     => $file->mime_type,

                                                  source        => $file->source,

                                                  file_type     => $file->file_type,

                                                  file_name     => $params{to}

                                                ) > 0;

    my $backend = $self->_get_backend($file->backend);

    $backend->rename(dbfile => $file) if $backend;

    $file->file_name($params{to});

    $file->save;

  }

  return RENAME_OK;

}

sub get_backend_class {

  my ($self, $backendname) = @_;

  die "no backend name set" unless $backendname;

  $self->_get_backend($backendname);

}

sub get_other_sources {

  my ($self) = @_;

  my $pref = SL::Helper::UserPreferences->new(namespace => 'file_sources');

  $pref->login("#default#");

  my @sources;

  foreach my $tuple (@{ $pref->get_all() }) {

    my %lkeys  = %{ SL::JSON::from_json($tuple->{value}) };

    my $source = {

      'name'        => $tuple->{key},

      'description' => $lkeys{desc},

      'directory'   => $lkeys{dir}

    };

    push @sources, $source;

  }

  return @sources;

}

sub sync_from_backend {

  my ($self, %params) = @_;

  return unless $params{file_type};

  my $file = SL::DB::File->new;

  $file->file_type($params{file_type});

  my $backend = $self->_get_backend(dbfile => $file->backend);

  return unless $backend;

  $backend->sync_from_backend(%params);

}

#

# internal

#

sub _get_backend {

  my ($self, $backend_name) = @_;

  my $class = 'SL::File::Backend::' . $backend_name;

  my $obj   = undef;

  eval {

    eval "require $class";

    $obj = $class->new;

    die \'backend not enabled' unless $obj->enabled;

    1;

  } or do {

    die \'backend class not found';

  };

  return $obj;

}

sub _get_backend_by_file_type {

  my ($self, $dbfile) = @_;

  $main::lxdebug->message(LXDebug->DEBUG2(), "_get_backend_by_file_type=" .$dbfile." type=".$dbfile->file_type);

  return "Filesystem" unless $dbfile;

  return $::instance_conf->get_doc_storage_for_documents   if $dbfile->file_type eq 'document';

  return $::instance_conf->get_doc_storage_for_attachments if $dbfile->file_type eq 'attachment';

  return $::instance_conf->get_doc_storage_for_images      if $dbfile->file_type eq 'image';

  return "Filesystem";

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

SL::File - The intermediate Layer for handling files

=head1 SYNOPSIS

  # In a controller or helper ( see SL::Controller::File or SL::Helper::File )

  # you can create, remove, delete etc. a file in a backend independant way

  my $file  = SL::File->save(

                     object_id     => $self->object_id,

                     object_type   => $self->object_type,

                     mime_type     => 'application/pdf',

                     file_type     => 'documents',

                     file_contents => 'this is no pdf');

  my $file1  = SL::File->get(id => $id);

  SL::File->delete(id => $id);

  SL::File->delete(dbfile => $file1);

  SL::File->delete_all(object_id   => $object_id,

                       object_type => $object_type,

                       file_type   => $filetype      # may be optional

                      );

  SL::File->rename(id => $id,to => $newname);

  my $files1 = SL::File->get_all(object_id   => $object_id,

                                 object_type => $object_type,

                                 file_type   => 'images',  # may be optional

                                 source      => 'uploaded' # may be optional

                                );

  # Alternativelly some operation can be done with the filemangement object wrapper

  # and additional oparations see L<SL::File::Object>

=head1 OVERVIEW

The Filemanagemt can handle files in a storage independant way. Internal the File

use the configured storage backend for the type of file.

These backends must be configured in L<SL::Controller::ClientConfig> or an extra database table.

There are three types of files:

=over 2

=item - documents,

which can be generated files (for sales), scanned files or uploaded files (for purchase) for an ERP-object.

They can exist in different versions. The versioning is handled implicit. All versions of a file may be

deleted by the user if she/he is allowed to do this.

=item - attachments,

which have additional information for an ERP-objects. They are uploadable. If a filename still exists

on a ERP-Object the new uploaded file is a new version of this or it must be renamed by user.

There are generic attachments for a specific document group (like sales_invoices). This attachments can be

combinide/merged with the document-file in the time of printing.

Today only PDF-Attachmnets can be merged with the generated document-PDF.

=item - images,

they are like attachments, but they may be have thumbnails for displaying.

So the must have an image format like png,jpg. The versioning is like attachments

=back

For each type of files the backend can configured in L<SL::Controller::ClientConfig>.

The files have also the parameter C<Source>:

=over 2

=item - created, generated by LaTeX

=item - uploaded

=item - scanner, import from scanner

( or scanner1, scanner2 if there are different scanner, be configurable via UserPreferences )

=item - email, received by email and imported by hand or automatic.

=back

The files from source 'scanner' or 'email' are not allowed to delete else they must be send back to the sources.

This means they are moved back into the correspondent source directories.

The scanner and email import must be configured  via Table UserPreferences:

=begin text

 id |  login  |  namespace   | version |   key    |                        value

----+---------+--------------+---------+----------+------------------------------------------------------

  1 | default | file_sources | 0.00000 | scanner1 | {"dir":"/var/tmp/scanner1","desc":"Scanner Einkauf" }

  2 | default | file_sources | 0.00000 | emails   | {"dir":"/var/tmp/emails"  ,"desc":"Empfangene Mails"}

=end text

.

The Fileinformation is stored in the table L<SL::DB::File> for saving the information.

The modul and object_id describe the link to the object.

The interface SL::File:Object encapsulate SL::DB:File, see L<SL::DB::Object>

The storage backends are extra classes which depends from L<SL::File::Backend>.

So additional backend classes can be added.

The implementation of versioning is done in the different backends.

=head1 METHODS

=over 4

=item C<save>

Creates a new SL::DB:File object or save an existing object for a specific backend depends of the C<file_type>

and config, like

=begin text

          SL::File->save(

                         object_id    => $self->object_id,

                         object_type  => $self->object_type,

                         content_type => 'application/pdf'

                        );

=end text

.

The file data is stored in the backend. If the file_type is "document" and the source is not "created" the file is imported,

so in the history the import is documented also as a hint to can unimport the file later.

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File for an existing file

=item C<object_id>

The Id of the ERP-object for a new file.

=item C<object_type>

The Type of the ERP-object like "sales_quotation" for a new file. A clear mapping to the class/model exists in the controller.

=item C<file_type>

The type may be "documents", "attachments" or "images" for a new file.

=item C<source>

The type may be "created", "uploaded" or email sources or scanner sources for a new file.

=item C<file_name>

The file_name of the file for a new file. This name is used in the WebGUI and as name for download.

=item C<mime_type>

The mime_type of a new file. This is used for downloading or for email attachments.

=item C<description> or C<title>

The description or title of a new file. This must be discussed if this attribute is needed.

=back

=item C<delete PARAMS>

The file data is deleted in the backend. If the file comes from source 'scanner' or 'email'

they moved back to the source folders. This is documented in the history.

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File

=item C<dbfile>

As alternative if the SL::DB::File as object is available.

=back

=item C<delete_all PARAMS>

All file data of an ERP-object is deleted in the backend.

=over 4

=item C<object_id>

The Id of the ERP-object.

=item C<object_type>

The Type of the ERP-object like "sales_quotation". A clear mapping to the class/model exists in the controller.

=back

=item C<rename PARAMS>

The Filename of the file is changed

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File

=item C<to>

The new filename

=back

=item C<get PARAMS>

The actual file object is retrieved. The id of the object is needed.

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File

=back

=item C<get_all PARAMS>

All last versions of file data objects which are related to an ERP-Document,Part,Customer,Vendor,... are retrieved.

Available C<PARAMS>:

=over 4

=item C<object_id>

The Id of the ERP-object.

=item C<object_type>

The Type of the ERP-object like "sales_quotation". A clear mapping to the class/model exists in the controller.

=item C<file_type>

The type may be "documents", "attachments" or "images". This parameter is optional.

=item C<file_name>

The name of the file . This parameter is optional.

=item C<mime_type>

The MIME type of the file . This parameter is optional.

=item C<source>

The type may be "created", "uploaded" or email sources or scanner soureces. This parameter is optional.

=item C<sort_by>

An optional parameter in which sorting the files are retrieved. Default is decrementing itime and ascending filename

=back

=item C<get_all_versions PARAMS>

All versions of file data objects which are related to an ERP-Document,Part,Customer,Vendor,... are retrieved.

If only the versions of one file are wanted, additional parameter like file_name must be set.

If the param C<dbfile> set, only the versions of this file are returned.

Available C<PARAMS> ar the same as L<get_all>

=item C<get_all_count PARAMS>

The count of available files is returned.

Available C<PARAMS> ar the same as L<get_all>

=item C<get_content PARAMS>

The data of a file can retrieved. A reference to the data is returned.

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File

=item C<dbfile>

If no Id exists the object SL::DB::File as param.

=back

=item C<get_file_path PARAMS>

Sometimes it is more useful to have a path to the file not the contents. If the backend has not stored the content as file

it is in the responsibility of the backend to create a tempory session file.

Available C<PARAMS>:

=over 4

=item C<id>

The id of SL::DB::File

=item C<dbfile>

If no Id exists the object SL::DB::File as param.

=back

=item C<get_other_sources>

A helpful method to get the sources for scanner and email from UserPreferences. This method is need from SL::Controller::File

=item C<sync_from_backend>

For Backends which may be changed outside of kivitendo a synchronization of the database is done.

This sync must be triggered by a periodical task.

Needed C<PARAMS>:

=over 4

=item C<file_type>

The synchronization is done file_type by file_type.

=back

=back

=head1 AUTHOR

Martin Helmling E<lt>martin.helmling@opendynamic.deE<gt>

=cut

package SL::File::Backend;

use strict;

use parent qw(Rose::Object);

sub store { die 'store needs to be implemented' }

sub delete { die 'delete needs to be implemented' }

sub rename { die 'rename needs to be implemented' }

sub get_content { die 'get_content needs to be implemented' }

sub get_filepath { die 'get_filepath needs to be implemented' }

sub get_mtime { die 'get_mtime needs to be implemented' }

sub get_version_count { die 'get_version_count needs to be implemented' }

sub enabled { 0; }

sub sync_from_backend { }

1;

__END__

=pod

=encoding utf8

=head1 NAME

SL::File::Backend  - Base class for file storage backend

=head1 SYNOPSIS

See the synopsis of L<SL::File> and L<SL::File::Object>

=head1 OVERVIEW

The most methods must be overridden by the specific storage backend

See also the overview of L<SL::File> and L<SL::File::Object>.

=head1 METHODS

=over 4

=item C<store PARAMS>

The file data is stored in the backend.

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=item C<file_contents>

The data of the file to store

=item C<file_path>

If the data is still in a file, the contents of this file is copied.

=back

If both parameter C<file_contents> and C<file_path> exists,

the backend is responsible in which way the contents is fetched.

If the file exists the backend is responsible to decide to save a new version of the file or override the

latest existing file.

=item C<delete PARAMS>

The file data is deleted in the backend.

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=item C<last>

If this parameter is set only the latest version of the file are deleted.

=item C<all_but_notlast>

If this parameter is set all versions of the file are deleted except the latest version.

If none of the two parameters C<all_versions> or C<all__but_notlast> is set

all version of the file are deleted.

=back

=item C<rename PARAMS>

The Filename of the file is changed. If the backend is not dependant from the filename

nothing must happens. The rename must work on all versions of the file.

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=back

=item C<get_version_count PARAMS>

The count of the available versions of a file will returned.

The versions are numbered from 1 up to the returned value

Available C<PARAMS>:

=over 4

=item C<dbfile>

=back

=item C<get_mtime PARAMS>

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=item C<version>

The version number of the file for which the modification timestamp is wanted.

If no version set or version is 0 , the mtime of the latest version is returned.

=back

=item C<get_content PARAMS>

For downloading or printing the real data need to retrieve.

A reference of the data must be returned.

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=back

=item C<get_file_path PARAMS>

If the backend has files as storage, the file path can returned.

If a file is not available in the backend a temporary file must be created with the contents.

Available C<PARAMS>:

=over 4

=item C<dbfile>

The object SL::DB::File as param.

=back

=item C<enabled>

returns 1 if the backend is enabled and has all config to work.

In other cases it must return 0

=item C<sync_from_backend>

For Backends which may be changed outside of kivitendo a synchronization of the database is done.

Normally the backend is responsible to actualise the data if it needed.

This interface can be used if a long work must be done and runs in a extra task.

=back

=head1 SEE ALSO

L<SL::File>, L<SL::File::Object>

=head1 AUTHOR

Martin Helmling E<lt>martin.helmling@opendynamic.deE<gt>

=cut

package SL::File::Object;

use strict;

use parent qw(Rose::Object);

use DateTime;

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw() ],

  'scalar --get_set_init' => [ qw(db_file loaded id version newest) ],

);

#use SL::DB::Helper::Attr;

#__PACKAGE__->_as_timestamp('mtime');

# wie wird das mit dem Attr Helper gemacht damit er bei nicht DB Objekten auch geht?

sub mtime_as_timestamp_s {

  $::locale->format_date_object($_[0]->mtime, precision => 'second');

}

# wrapper methods

sub itime {

  $_[0]->loaded_db_file->itime;

}

sub file_name {

  $_[0]->loaded_db_file->file_name;

}

sub file_type {

  $_[0]->loaded_db_file->file_type;

}

sub file_name {

  $_[0]->loaded_db_file->file_name;

}

sub object_type {

  $_[0]->loaded_db_file->object_type;

}

sub object_id {

  $_[0]->loaded_db_file->object_id;

}

sub mime_type {

  $_[0]->loaded_db_file->mime_type;

}

sub file_title {

  $_[0]->loaded_db_file->title;

}

sub file_description {

  $_[0]->loaded_db_file->description;

}

sub backend {

  $_[0]->loaded_db_file->backend;

}

sub source {

  $_[0]->loaded_db_file->source;

}

# methods to go directly into the backends

sub get_file {

  $_[0]->backend_class->get_filepath(dbfile => $_[0]->loaded_db_file, version => $_[0]->version)

}

sub get_content {

  $_[0]->backend_class->get_content(dbfile => $_[0]->loaded_db_file,  version => $_[0]->version)

}

sub mtime {

  $_[0]->backend_class->get_mtime(dbfile => $_[0]->loaded_db_file, version => $_[0]->version)

}

sub version_count {

  $_[0]->backend_class->get_version_count(dbfile => $_[0]->loaded_db_file)

}

sub versions {

  SL::File->get_all_versions(dbfile => $_[0]->loaded_db_file)

}

sub save_contents {

  SL::File->save(dbfile => $_[0]->loaded_db_file, file_contents => $_[1] )

}

sub save_file {

  SL::File->save(dbfile => $_[0]->loaded_db_file, file_path => $_[1] )

}

sub delete {

  SL::File->delete(dbfile => $_[0]->loaded_db_file)

}

sub delete_last_version {

  SL::File->delete(dbfile => $_[0]->loaded_db_file, last => 1 )

}

sub purge {

  SL::File->delete(dbfile => $_[0]->loaded_db_file, all_but_notlast => 1 )

}

sub rename {

  SL::File->rename(dbfile => $_[0]->loaded_db_file, to => $_[1])

}

# internals

sub backend_class {

  SL::File->get_backend_class($_[0]->backend)

}

sub loaded_db_file {  # so, dass wir die nur einmal laden.

  if (!$_[0]->loaded) {

    $_[0]->db_file->load;

    $_[0]->loaded(1);

  }

  $_[0]->db_file;

}

sub init_db_file { die 'must always have a db file'; }

sub init_loaded  { 0 }

sub init_id      { 0 }

sub init_version { 0 }

sub init_newest  { 1 }

1;

__END__

=encoding utf-8

=head1 NAME

SL::File::Object - a filemangement object wrapper

=head1 SYNOPSIS

  use SL::File;

  my ($object) = SL::File->get_all(object_id   => $object_id,

                                   object_type => $object_type,

                                   file_type   => 'images',  # may be optional

                                   source      => 'uploaded' # may be optional

                                  );

# read attributes

  my $object_id   = $object->object_id,

  my $object_type = $object->object_type,

  my $file_type   = $object->file_type;

  my $file_name   = $object->file_name;

  my $mime_type   = $object->mime_type;

  my $mtime       = $object->mtime;

  my $itime       = $object->itime;

  my $id          = $object->id;

  my $newest      = $object->newest;

  my $versions    = $object->version_count;

  my @versionobjs = $object->versions;

  foreach ( @versionobjs ) {

    my $mtime    = $_->mtime;

    my $contents = $_->get_content;

  }

# update

  $object->rename("image1.png");

  $object->save_contents("new text");

  $object->save_file("/tmp/empty.png");

  $object->purge;

  $object->delete_last_version;

  $object->delete;

=head1 DESCRIPTION

This is a wrapper around a single object in the filemangement.

=head1 METHODS

Following methods are wrapper to read the attributes of L<SL::DB::File> :

=over 4

=item C<object_id>

=item C<object_type>

=item C<file_type>

=item C<file_name>

=item C<mime_name>

=item C<file_title>

=item C<file_description>

=item C<backend>

=item C<source>

=item C<itime>

=item C<id>

=back

Additional are there special methods. If the Object is created by SL::File::get_all_versions()

or by "$object->versions"

it has a version number. So the different mtime, filepath or content can be retrieved:

=over 4

=item C<mtime>

get the modification time of a (versioned) object

=item C<get_file>

get the full qualified file path of the (versioned) object

=item C<get_content>

get the content of the (versioned) object

=item C<version_count>

Get the available versions of the file

=item C<versions>

Returns an array of SL::File::Object objects with the available versions of the file, starting with the newest version.

=item C<newest>

If set this is the newest version of the file.

=item C<save_contents $contents>

Store a new contents to the file (as a new version).

=item C<save_file $filepath>

Store the content of an (absolute)file path to the file

=item C<delete>

Delete the file with all of his versions

=item C<delete_last_version>

Delete only the last version of the file with implicit decrement of the version_count.

=item C<purge>

Delete all old versions of the file. Only one version exist after purge. The version count is reset to 1.

=item C<rename $newfilename>

Renames the filename

=back

=head1 SEE ALSO

L<SL::File>

=head1 AUTHOR

Martin Helmling E<lt>martin.helmling@opendynamic.deE<gt>

=cut