Net::LDAP::DSML

Net::LDAP::DSML(3)   User Contributed Perl Documentation   Net::LDAP::DSML(3)



NAME
       NET::LDAP::DSML -- A DSML Writer for Net::LDAP

SYNOPSIS
	For a directory entry;

	use Net::LDAP;
	use Net::LDAP::DSML;
	use IO::File;

	my $server = "localhost";
	my $file = "testdsml.xml";
	my $ldap = Net::LDAP->new($server);

	$ldap->bind();

	#
	# For file i/o
	#
	my $file = "testdsml.xml";

	my $io = IO::File->new($file,"w") or die ("failed to open $file as filehandle.$!\n");

	my $dsml = Net::LDAP::DSML->new(output => $io, pretty_print => 1 )
	     or die ("DSML object creation problem using an output file.\n");
	#      OR
	#
	# For file i/o
	#

	open (IO,">$file") or die("failed to open $file.$!");

	my $dsml = Net::LDAP::DSML->new(output => *IO, pretty_print => 1)
	    or die ("DSML object creation problem using an output file.\n");

	#      OR
	#
	# For array usage.
	# Pass a reference to an array.
	#

	my @data = ();
	$dsml = Net::LDAP::DSML->new(output => \@data, pretty_print => 1)
	    or die ("DSML object cration problem using an output array.\n");

	 my $mesg = $ldap->search(
				  base	   => ’o=airius.com’,
				  scope	   => ’sub’,
				  filter   => ’ou=accounting’,
				  callback => sub {
						my ($mesg,$entry) =@_;
						$dsml->write_entry($entry)
						 if (ref $entry eq ’Net::LDAP::Entry’);
					      }
				   );

	die ("search failed with ",$mesg->code(),"\n") if $mesg->code();

	For directory schema;

	A file or array can be used for output, in the following example
	only an array will be used.

	my $schema = $ldap->schema();
	my @data = ();
	my $dsml = Net::LDAP::DSML->new(output => \@data, pretty_print => 1 )
	     or die ("DSML object creation problem using an output array.\n");

	$dsml->write_schema($schema);

	print "Finished printing DSML\n";

DESCRIPTION
       Directory Service Markup Language (DSML) is the XML standard for rep-
       resenting directory service information in XML.

       At the moment this module only writes DSML entry and schema entities.
       Reading DSML entities is a future project.

       Eventually this module will be a full level 2 consumer and producer
       enabling you to give you full DSML conformance.	Currently this module
       has the ability to be a level 2 producer.  The user must understand
       the his/her directory server will determine the consumer and producer
       level they can achieve.

       To determine conformance, it is useful to divide DSML documents into
       four types:

	 1.Documents containing no directory schema nor any references to
	   an external schema.
	 2.Documents containing no directory schema but containing at
	   least one reference to an external schema.
	 3.Documents containing only a directory schema.
	 4.Documents containing both a directory schema and entries.

       A producer of DSML must be able to produce documents of type 1.	A
       producer of DSML may, in addition, be able to produce documents of
       types 2 thru 4.

       A producer that can produce documents of type 1 is said to be a level
       1 producer. A producer than can produce documents of all four types is
       said to be a level 2 producer.

CALLBACKS
       The module uses callbacks to improve performance (at least the appear-
       ance of improving performance ;) and to reduce the amount of memory
       required to parse large DSML files. Every time a single entry or
       schema is processed we pass the Net::LDAP object (either an Entry or
       Schema object) to the callback routine.

CONSTRUCTOR
       new ()
	   Creates a new Net::LDAP::DSML object.  There are 2 options to this
	   method.

	   "output" is a reference to either a file handle that has already
	   been opened or to an array.

	   "pretty_print" is an option to print a new line at the end of each
	   element sequence.  It makes the reading of the XML output easier
	   for a human.

	   Example

	     my $dsml = Net::LDAP::DSML->new();
	     Prints xml data to standard out.

	     my $dsml = Net::LDAP::DSML->new(output => \@array);
	     my $dsml = Net::LDAP::DSML->new(output => *FILE);
	     Prints xml data to a file or array.

	     my $dsml = Net::LDAP::DSML->new(output => \@array, pretty_print => 1);
	     my $dsml = Net::LDAP::DSML->new(output => *FILE, pretty_print => 1);
	     Prints xml data to a file or array in pretty print style.

METHODS
       start_dsml ()
	   Start a DSML file.

       end_dsml ()
	   End a DSML file.

       write_entry ( ENTRY )
	   Entry is a Net::LDAP::Entry object. The write method will parse
	   the LDAP data in the Entry object and put it into DSML XML format.

	   Example

	     my $entry = $mesg->entry();
	     $dsml->write_entry($entry);

       write_schema ( SCHEMA )
	   Schema is a Net::LDAP::Schema object. The write_schema method will
	   parse the LDAP data in the Schema object and put it into DSML XML
	   format.

	   Example

	     my $schema = $ldap->schema();
	     $dsml->write_schema($schema);

AUTHOR
       Graham Barr   gbarr@pobox.com

SEE ALSO
       Net::LDAP, XML::SAX::Base

COPYRIGHT
       Copyright (c) 2002-2006 Graham Barr. All rights reserved. This program
       is free software; you can redistribute it and/or modify it under the
       same terms as Perl itself.



perl v5.8.8			  2008-10-27		   Net::LDAP::DSML(3)