diff -r 6d08f4a05d93 -r 3145852acc89 releasing/cbrtools/perl/Symbian/IPR.pm
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/releasing/cbrtools/perl/Symbian/IPR.pm	Fri Jun 25 18:37:20 2010 +0800
@@ -0,0 +1,325 @@
+# Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+# All rights reserved.
+# This component and the accompanying materials are made available
+# under the terms of the License "Eclipse Public License v1.0"
+# which accompanies this distribution, and is available
+# at the URL "http://www.eclipse.org/legal/epl-v10.html".
+# 
+# Initial Contributors:
+# Nokia Corporation - initial contribution.
+# 
+# Contributors:
+# 
+# Description:
+# 
+#
+# Description:
+# Symbian::IPR
+#
+
+package Symbian::IPR;
+
+use strict;
+use Carp;
+use Symbian::CBR::IPR::MRP;
+use Symbian::DistributionPolicy::Reader;
+
+use base qw(Class::Singleton);
+
+
+sub _new_instance {
+    my $pkg = shift;
+    my $useDistPolFirst = shift;
+    my $disallowUnclassifiedSource = shift;
+    my $typeOfMrp = shift;
+    my $verbose = shift;
+    my $captureDistributionPolicyOutput = shift;
+    
+    if (!$typeOfMrp || shift) {
+        # caller(0))[3] gives the package and the method called, e.g. Symbian::IPR::_new_instance
+        croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+    }
+
+    my $self = {
+            'useDistPolFirst' => $useDistPolFirst,
+            'disallowUnclassifiedSource' => $disallowUnclassifiedSource,
+            'verbose' => $verbose,
+            'typeOfMrp' => $typeOfMrp,
+            'captureDistributionPolicyOutput' => $captureDistributionPolicyOutput};
+
+    bless $self, $pkg;
+
+    if (!$useDistPolFirst) {
+        # If we are not using distribution policy files as default then create a Symbian::CBR::IPR::MRP object... 
+        $self->CreateMrpObject();
+    }
+    
+    return $self;
+}
+
+sub CreateMrpObject {
+    my $self = shift;
+    
+    if (!exists $self->{'mrpObject'}) {
+        $self->{'mrpObject'} = Symbian::CBR::IPR::MRP->instance($self->{typeOfMrp}, $self->{verbose});
+    }
+    
+    # We may have cached calls to PrepareInformationForComponent...
+    if (defined $self->{prepareInformationForComponentCache}) {
+        foreach my $component (@{$self->{prepareInformationForComponentCache}}) {
+            $self->PrepareInformationForComponent($component);
+        }
+        delete $self->{prepareInformationForComponentCache};
+    }
+    
+    # and also to PrepareInformationForMrpFile...
+    if (defined $self->{prepareInformationForMrpFileCache}) {
+        $self->PrepareInformationForMrpFile->(@{$self->{prepareInformationForMrpFileCache}});
+        delete $self->{prepareInformationForMrpFileCache};
+    }
+}
+
+sub PrepareInformationForComponent {
+    my $self = shift;
+    my $component = shift;
+    
+    # An MRP object may not have been created, for example if using distribution policy files first.
+    # In that case we cache the calls to PrepareInformationForComponent, and will pass them onto the
+    # MRP object if it is ever created.
+    if (defined $self->{'mrpObject'}) {
+        $self->{'mrpObject'}->PrepareInformationForComponent($component);
+    }
+    else {
+        push @{$self->{prepareInformationForComponentCache}}, $component;
+    }
+}
+
+sub PrepareInformationForMrpFile {
+    my $self = shift;
+    my @mrps = shift;   
+
+    # An MRP object may not have been created, for example if using distribution policy files first.
+    # In that case we cache the calls to PrepareInformationForMrpFile, and will pass them onto the
+    # MRP object if it is ever created.
+    if (defined $self->{'mrpObject'}) {
+        $self->{'mrpObject'}->PrepareInformationForMrpFile(@mrps);
+    }
+    else {
+        push @{$self->{prepareInformationForMrpFileCache}}, @mrps;
+    }
+}
+
+
+sub Category {
+    my $self = shift;
+    my $path = shift;
+
+    if (!$path || shift) {
+        croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+    }
+    
+    my ($category, $errors) = $self->GetRequestedInformation($path, 'Category');
+
+    if (!$category) {
+        $category = 'X';
+    }
+
+    return ($category, $errors);
+}
+
+sub ExportRestricted {
+    my $self = shift;
+    my $path = shift;
+
+    if (!$path || shift) {
+        croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+    }
+
+    my ($exportRestricted, $errors) = $self->GetRequestedInformation($path, 'ExportRestricted');
+
+    return ($exportRestricted, $errors);
+}
+
+sub GetRequestedInformation {
+    my $self = shift;
+    my $path = shift;
+    my $what = shift;
+
+    my @errors; # This collects the errors produced from the distribution policy modules.
+                # The CBR Tools handle these errors in a different way.
+
+    if (!$path || !$what || shift) {
+        croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
+    }
+    
+    my $result = undef;
+    my $informationFrom = undef;
+    
+    if (!$self->{useDistPolFirst} && $self->{mrpObject}) {
+        # If to use MRP files first and an Mrp object exists...
+        $result = $self->{mrpObject}->$what($path);
+
+        $informationFrom = 'M' if (defined $result);
+    }
+    
+    if (! defined $result) {
+        # If  distribution policies are to be used first or could not obtain information
+        # from MRP object then use distribution policies
+
+        # Create a distribution policy reader if one does not already exist...
+        if (!$self->{distPolReader}) {
+            # Create a distribution policy reader if one does not already exist...
+            $self->{distPolReader} = Symbian::DistributionPolicy::Reader->new();
+        }
+        
+        if ($self->{distPolReader}->isa("Symbian::DistributionPolicy::Reader")) {
+            my $warner;
+            
+            # We may need to capture the output of the distribution policy modules
+            if ($self->{'captureDistributionPolicyOutput'}) {
+                $warner = sub { push @errors, shift; };
+            }
+            local $SIG{__WARN__} = $warner if ($warner);
+
+            # We want to make sure that we do have a reader before trying to read a file
+            eval {  my $distPolObj = $self->{distPolReader}->ReadPolicyFile($path);
+                    $result = $distPolObj->$what()};
+
+            $informationFrom = 'D' if (defined $result);
+        }
+    }
+
+    if ((!defined $result) && $self->{useDistPolFirst}) {
+        # If distribution policies have been used first and failed then try getting the information from MRP files...
+        
+        # The Symbian::CBR::IPR::MRP might not yet have been created
+        if (!exists $self->{mrpObject}) {
+            $self->CreateMrpObject();
+        }
+        
+        $result = $self->{mrpObject}->$what($path);
+
+        $informationFrom = 'M' if (defined $result);
+    }
+   
+    if (!defined $informationFrom && $self->{disallowUnclassifiedSource}) {
+        carp "Warning: IPR information for '$path' could not be obtained from either MRP files or distribution policy files\n";
+    }
+        
+    if ($self->{verbose} > 1) {
+        # If verbose then we print information saying where the IPR information was obtained from
+        if ($informationFrom eq 'M') {
+            print "Info: IPR information for '$path' was obtained using MRP files\n";
+        }
+        elsif ($informationFrom eq 'D') {
+            print "Info: IPR information for '$path' was obtained using Distribution Policy files\n";
+        }        
+    }
+
+    return ($result, \@errors);
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Symbian::IPR - An interface to IPR information within MRP files and Distribution
+Policy files.
+
+=head1 SYNOPSIS
+
+use Symbian::IPR;
+
+ # Instantiate a Symbian::IPR object
+ my $iprObject = Symbian::IPR->instance(0, 0, 'MRP', undef, 1);
+
+ # Get the IPR category for a path
+ my $category = $iprObject->Category('\aPath\somewhere');
+
+ # Get the export restricted flag for a path
+ my $exportRestricted = $iprObject->ExportRestricted('\aPath\somewhere');
+
+=head1 DESCRIPTION
+
+This package provides an interface to obtaining IPR information from MRP files
+and Distribution Policy files.  The user can specify the order of preference
+between MRP and distribution policies.  If the requested information can not be
+obtained from the preferred choice then the package will fall back to using the
+other option.
+
+=head1 METHODS
+
+=head2 new(useDistPolFirst, disallowUnclassifiedSource, typeOfMrp, component, verbose)
+
+Instantiates a Symbian::IPR object.
+
+The default order is for IPR information to be obtained from MRP files first, and
+if unsuccessful then to obtain the IPR information from distribution policy files.
+If the boolean value useDistPolFirst is specified then IPR information will be
+obtained from distribution policy files by default, and if not successful then
+MRP files will be used.
+
+If the disallowUnclassifiedSource flag is specified then warnings will be produced
+if IPR information can not be obtained both MRP files and distribution.policy files.
+
+The typeOfMrp argument is non-optional.  Valid types are MRP and MRPDATA.  See the
+documentation for Symbian::CBR::MRP::Reader for more information.
+
+If a component had been specified then the MRP file for the component will be processed
+and the IPR information obtained.  Any MRP files for dependant components will be
+located and processed too.  If no component name has been specified all MRP files
+in the environment will be processed.
+
+=head2 Category(path)
+
+Returns the IPR category of the path.  If no IPR information exists for the
+specified path then X will be returned.
+
+=head2 ExportRestricted(path)
+
+Returns true if the specified path is export restricted, and false if it is not.
+If no IPR information exists for the specified path then undef will be returned.
+
+=head2 PrepareInformationForComponent(component_name)
+
+If using MRP files for IPR information it is possible to specify which components
+contain the information required.  This improves performance as only required
+MRP files are processed.  The default behaviour is to process all MRP files listed
+in the CBR Tools environment database.
+
+If using distribution policy files as default then information passed to this method
+will be cached and realised only if it becomes necessary to use MRP files for IPR
+information (e.g. distribution policy file does not exist).
+
+=head2 PrepareInformationForMrpFile(list_of_mrp_files)
+
+If using MRP files for IPR information it is possible to specify which MRP files
+contain the information required.  This can be used in scenarios where a CBR Tools
+environment database does not exist, and so MRP locations are unknown.
+
+If using distribution policy files as default then information passed to this method
+will be cached and realised only if it becomes necessary to use MRP files for IPR
+information (e.g. distribution policy file does not exist).
+
+=head1 COPYRIGHT
+
+ Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
+ All rights reserved.
+ This component and the accompanying materials are made available
+ under the terms of the License "Eclipse Public License v1.0"
+ which accompanies this distribution, and is available
+ at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ 
+ Initial Contributors:
+ Nokia Corporation - initial contribution.
+ 
+ Contributors:
+ 
+ Description:
+ 
+
+=cut