###
XML
###


****
NAME
****


Kernel::System::XML - xml lib


***********
DESCRIPTION
***********


All xml related functions.


****************
PUBLIC INTERFACE
****************


new()
=====


Don't use the constructor directly, use the ObjectManager instead:


.. code-block:: perl

     my $XMLObject = $Kernel::OM->Get('Kernel::System::XML');



XMLHashAdd()
============


add an XMLHash to storage


.. code-block:: perl

     my $Key = $XMLObject->XMLHashAdd(
         Type    => 'SomeType',
         Key     => '123',
         XMLHash => \@XMLHash,
     );
 
     my $AutoKey = $XMLObject->XMLHashAdd(
         Type             => 'SomeType',
         KeyAutoIncrement => 1,
         XMLHash          => \@XMLHash,
     );



XMLHashUpdate()
===============


update an XMLHash to storage


.. code-block:: perl

     $XMLHash[1]->{Name}->[1]->{Content} = 'Some Name';
 
     $XMLObject->XMLHashUpdate(
         Type    => 'SomeType',
         Key     => '123',
         XMLHash => \@XMLHash,
     );



XMLHashGet()
============


get an XMLHash from the database


.. code-block:: perl

     my @XMLHash = $XMLObject->XMLHashGet(
         Type => 'SomeType',
         Key  => '123',
     );
 
     my @XMLHash = $XMLObject->XMLHashGet(
         Type  => 'SomeType',
         Key   => '123',
         Cache => 0,   # (optional) do not use cached data
     );



XMLHashDelete()
===============


delete an XMLHash from the database


.. code-block:: perl

     $XMLObject->XMLHashDelete(
         Type => 'SomeType',
         Key  => '123',
     );



XMLHashMove()
=============


move an XMLHash from one type or/and key to another


.. code-block:: perl

     $XMLObject->XMLHashMove(
         OldType => 'SomeType',
         OldKey  => '123',
         NewType => 'NewType',
         NewKey  => '321',
     );



XMLHashSearch()
===============


Search an XMLHash in the database.


.. code-block:: perl

     my @Keys = $XMLObject->XMLHashSearch(
         Type => 'SomeType',
         What => [
             # each array element is a and condition
             {
                 # or condition in hash
                 "[%]{'ElementA'}[%]{'ElementB'}[%]{'Content'}" => '%contentA%',
                 "[%]{'ElementA'}[%]{'ElementC'}[%]{'Content'}" => '%contentA%',
             },
             {
                 "[%]{'ElementA'}[%]{'ElementB'}[%]{'Content'}" => '%contentB%',
                 "[%]{'ElementA'}[%]{'ElementC'}[%]{'Content'}" => '%contentB%',
             },
             {
                 # use array reference if different content with same key was searched
                 "[%]{'ElementA'}[%]{'ElementB'}[%]{'Content'}" => ['%contentC%', '%contentD%', '%contentE%'],
                 "[%]{'ElementA'}[%]{'ElementC'}[%]{'Content'}" => ['%contentC%', '%contentD%', '%contentE%'],
             },
         ],
     );



XMLHashList()
=============


generate a list of XMLHashes in the database


.. code-block:: perl

     my @Keys = $XMLObject->XMLHashList(
         Type => 'SomeType',
     );



XMLHash2XML()
=============


generate an XML string from an XMLHash


.. code-block:: perl

     my $XMLString = $XMLObject->XMLHash2XML(@XMLHash);



XMLParse2XMLHash()
==================


parse an XML file and return an XMLHash structure


.. code-block:: perl

     my @XMLHash = $XMLObject->XMLParse2XMLHash( String => $FileString );
 
     XML:
     ====
     <Contact role="admin" type="organization">
         <Name type="long">Example Inc.</Name>
         <Email type="primary">info@exampe.com<Domain>1234.com</Domain></Email>
         <Email type="secondary">sales@example.com</Email>
         <Telephone country="germany">+49-999-99999</Telephone>
     </Contact>
 
     ARRAY:
     ======
     @XMLHash = (
         undef,
         {
             Contact => [
                 undef,
                 {
                     role => 'admin',
                     type => 'organization',
                     Name => [
                         undef,
                         {
                             Content => 'Example Inc.',
                             type => 'long',
                         },
                     ],
                     Email => [
                         undef,
                         {
                             type => 'primary',
                             Content => 'info@exampe.com',
                             Domain => [
                                 undef,
                                 {
                                     Content => '1234.com',
                                 },
                             ],
                         },
                         {
                             type => 'secondary',
                             Content => 'sales@exampe.com',
                         },
                     ],
                     Telephone => [
                         undef,
                         {
                             country => 'germany',
                             Content => '+49-999-99999',
                         },
                     ],
                 }
             ],
         }
     );
 
     $XMLHash[1]{Contact}[1]{TagKey} = "[1]{'Contact'}[1]";
     $XMLHash[1]{Contact}[1]{role} = "admin";
     $XMLHash[1]{Contact}[1]{type} = "organization";
     $XMLHash[1]{Contact}[1]{Name}[1]{TagKey} = "[1]{'Contact'}[1]{'Name'}[1]";
     $XMLHash[1]{Contact}[1]{Name}[1]{Content} = "Example Inc.";
     $XMLHash[1]{Contact}[1]{Name}[1]{type} = "long";
     $XMLHash[1]{Contact}[1]{Email}[1]{TagKey} = "[1]{'Contact'}[1]{'Email'}[1]";
     $XMLHash[1]{Contact}[1]{Email}[1]{Content} = "info\@exampe.com";
     $XMLHash[1]{Contact}[1]{Email}[1]{Domain}[1]{TagKey} = "[1]{'Contact'}[1]{'Email'}[1]{'Domain'}[1]";
     $XMLHash[1]{Contact}[1]{Email}[1]{Domain}[1]{Content} = "1234.com";
     $XMLHash[1]{Contact}[1]{Email}[2]{TagKey} = "[1]{'Contact'}[1]{'Email'}[2]";
     $XMLHash[1]{Contact}[1]{Email}[2]{type} = "secondary";
     $XMLHash[1]{Contact}[1]{Email}[2]{Content} = "sales\@exampe.com";



XMLHash2D()
===========


returns a simple hash with tag keys as keys and the values of \ ``XMLHash``\  as values.
As a side effect the data structure \ ``XMLHash``\  is enriched with tag keys.


.. code-block:: perl

     my %Hash = $XMLObject->XMLHash2D( XMLHash => \@XMLHash );


For example:


.. code-block:: perl

     $Hash{"[1]{'Planet'}[1]{'Content'}"'} = 'Sun';



XMLStructure2XMLHash()
======================


get an @XMLHash from a @XMLStructure with current TagKey param


.. code-block:: perl

     my @XMLHash = $XMLObject->XMLStructure2XMLHash( XMLStructure => \@XMLStructure );



XMLParse()
==========


parse an XML file


.. code-block:: perl

     my @XMLStructure = $XMLObject->XMLParse( String => $FileString );
 
     my @XMLStructure = $XMLObject->XMLParse( String => \$FileStringScalar );



_XMLHashAddAutoIncrement()
==========================


Generate a new integer key.
All keys for that type must be integers.


.. code-block:: perl

     my $Key = $XMLObject->_XMLHashAddAutoIncrement(
         Type             => 'SomeType',
         KeyAutoIncrement => 1,
     );