% Retrieve a ltpda_uo from a repository
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% FUNCTION:    fromRepository
%
% DESCRIPTION: Retrieve a ltpda_uo from a repository
%
% CALL:        obj = fromRepository(pl)
%
% PARAMETER:   pl: Parameter list object
%
% VERSION:     $Id: fromRepository.m,v 1.8 2010/10/29 16:09:11 ingo Exp $
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
function coll = fromRepository(coll, pl)

  VERSION = '$Id: fromRepository.m,v 1.8 2010/10/29 16:09:11 ingo Exp $';

  % get object info
  ii = collection.getInfo('collection', 'From Repository');
  % Set the method version string in the minfo object
  ii.setMversion([VERSION '-->' ii.mversion]);

  plh = copy(pl, 1);

  % Get parameters
  ids      = find(pl, 'id');
  cids     = find(pl, 'cid');
  bin      = find(pl, 'binary');

  collFound  = false;

  % check if using binary download
  bin = utils.prog.yes2true(bin);

  % database connection
  conn = LTPDADatabaseConnectionManager().connect(pl);

  if ~isempty(cids)
    for kk=1:numel(cids)
      cid = cids(kk);
      ids = utils.repository.getCollectionIDs(conn, cid);
    end
  end

  % Get each ID
  Nids     = length(ids);
  collObjs = {};

  for kk=1:Nids

    %---- copy the input plist because each object should get an other plist
    plh = copy(pl, 1);

    %---- This id
    id = ids(kk);
    utils.helper.msg(utils.const.msg.OPROC2, 'retrieving ID %d', id);

    try
      %---- call database constructor
      if bin
        robj = ltpda_uo.retrieve(conn, 'binary', id);
      else
        robj = ltpda_uo.retrieve(conn, id);
      end

      %---- Set connection parameters in the plist
      utils.repository.adjustPlist(conn, plh);

      %---- Set only the ID of the current object to the plist
      plh.pset('ID', id);

      %---- Add history
      robj.addHistoryWoChangingUUID(robj.getInfo(class(robj), 'From Repository'), plh, [], robj.hist);

      %---- Add to output array
      if isa(robj, 'collection')
        if numel(ids) == 1
          coll = robj;
          return
        end

        if numel(robj.objs)>0
          collFound = true;
          collObjs = [collObjs; robj.objs(:)];
        end
      else
        collObjs = [collObjs; {robj}];
      end
    
    catch ex
      % close connection if we own it
      if isempty(find(pl, 'conn'))
        conn.close();
      end
      throw(ex)
    end

  end

  % close connection if we own it
  if isempty(find(pl, 'conn'))
    conn.close();
  end

  if collFound
    warning(sprintf(['!!! The output collection contains the contents of at least one retrieved collection.' ...
      '\nThe history of those collection objects is discarded. The internal objects of those ' ...
      'objects is retained.']));
  end
  if isempty(collObjs)
    warning('!!! No objects were retrieved from the ids %s and/or collection id %s', mat2str(ids), mat2str(cid));
  end

  % Define collection-plist for the history
  plh.pset('id', pl.find('id'));
  plh.pset('cid', pl.find('cid'));

  % Set properties from the plist
  coll.setProperties(pl);
  coll.objs = collObjs;
  coll.addHistory(ii, plh, [], []);

end