releasing/cbrtools/perl/Symbian/IPR.pm
changeset 602 3145852acc89
equal deleted inserted replaced
600:6d08f4a05d93 602:3145852acc89
       
     1 # Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
       
     2 # All rights reserved.
       
     3 # This component and the accompanying materials are made available
       
     4 # under the terms of the License "Eclipse Public License v1.0"
       
     5 # which accompanies this distribution, and is available
       
     6 # at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
     7 # 
       
     8 # Initial Contributors:
       
     9 # Nokia Corporation - initial contribution.
       
    10 # 
       
    11 # Contributors:
       
    12 # 
       
    13 # Description:
       
    14 # 
       
    15 #
       
    16 # Description:
       
    17 # Symbian::IPR
       
    18 #
       
    19 
       
    20 package Symbian::IPR;
       
    21 
       
    22 use strict;
       
    23 use Carp;
       
    24 use Symbian::CBR::IPR::MRP;
       
    25 use Symbian::DistributionPolicy::Reader;
       
    26 
       
    27 use base qw(Class::Singleton);
       
    28 
       
    29 
       
    30 sub _new_instance {
       
    31     my $pkg = shift;
       
    32     my $useDistPolFirst = shift;
       
    33     my $disallowUnclassifiedSource = shift;
       
    34     my $typeOfMrp = shift;
       
    35     my $verbose = shift;
       
    36     my $captureDistributionPolicyOutput = shift;
       
    37     
       
    38     if (!$typeOfMrp || shift) {
       
    39         # caller(0))[3] gives the package and the method called, e.g. Symbian::IPR::_new_instance
       
    40         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
       
    41     }
       
    42 
       
    43     my $self = {
       
    44             'useDistPolFirst' => $useDistPolFirst,
       
    45             'disallowUnclassifiedSource' => $disallowUnclassifiedSource,
       
    46             'verbose' => $verbose,
       
    47             'typeOfMrp' => $typeOfMrp,
       
    48             'captureDistributionPolicyOutput' => $captureDistributionPolicyOutput};
       
    49 
       
    50     bless $self, $pkg;
       
    51 
       
    52     if (!$useDistPolFirst) {
       
    53         # If we are not using distribution policy files as default then create a Symbian::CBR::IPR::MRP object... 
       
    54         $self->CreateMrpObject();
       
    55     }
       
    56     
       
    57     return $self;
       
    58 }
       
    59 
       
    60 sub CreateMrpObject {
       
    61     my $self = shift;
       
    62     
       
    63     if (!exists $self->{'mrpObject'}) {
       
    64         $self->{'mrpObject'} = Symbian::CBR::IPR::MRP->instance($self->{typeOfMrp}, $self->{verbose});
       
    65     }
       
    66     
       
    67     # We may have cached calls to PrepareInformationForComponent...
       
    68     if (defined $self->{prepareInformationForComponentCache}) {
       
    69         foreach my $component (@{$self->{prepareInformationForComponentCache}}) {
       
    70             $self->PrepareInformationForComponent($component);
       
    71         }
       
    72         delete $self->{prepareInformationForComponentCache};
       
    73     }
       
    74     
       
    75     # and also to PrepareInformationForMrpFile...
       
    76     if (defined $self->{prepareInformationForMrpFileCache}) {
       
    77         $self->PrepareInformationForMrpFile->(@{$self->{prepareInformationForMrpFileCache}});
       
    78         delete $self->{prepareInformationForMrpFileCache};
       
    79     }
       
    80 }
       
    81 
       
    82 sub PrepareInformationForComponent {
       
    83     my $self = shift;
       
    84     my $component = shift;
       
    85     
       
    86     # An MRP object may not have been created, for example if using distribution policy files first.
       
    87     # In that case we cache the calls to PrepareInformationForComponent, and will pass them onto the
       
    88     # MRP object if it is ever created.
       
    89     if (defined $self->{'mrpObject'}) {
       
    90         $self->{'mrpObject'}->PrepareInformationForComponent($component);
       
    91     }
       
    92     else {
       
    93         push @{$self->{prepareInformationForComponentCache}}, $component;
       
    94     }
       
    95 }
       
    96 
       
    97 sub PrepareInformationForMrpFile {
       
    98     my $self = shift;
       
    99     my @mrps = shift;   
       
   100 
       
   101     # An MRP object may not have been created, for example if using distribution policy files first.
       
   102     # In that case we cache the calls to PrepareInformationForMrpFile, and will pass them onto the
       
   103     # MRP object if it is ever created.
       
   104     if (defined $self->{'mrpObject'}) {
       
   105         $self->{'mrpObject'}->PrepareInformationForMrpFile(@mrps);
       
   106     }
       
   107     else {
       
   108         push @{$self->{prepareInformationForMrpFileCache}}, @mrps;
       
   109     }
       
   110 }
       
   111 
       
   112 
       
   113 sub Category {
       
   114     my $self = shift;
       
   115     my $path = shift;
       
   116 
       
   117     if (!$path || shift) {
       
   118         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
       
   119     }
       
   120     
       
   121     my ($category, $errors) = $self->GetRequestedInformation($path, 'Category');
       
   122 
       
   123     if (!$category) {
       
   124         $category = 'X';
       
   125     }
       
   126 
       
   127     return ($category, $errors);
       
   128 }
       
   129 
       
   130 sub ExportRestricted {
       
   131     my $self = shift;
       
   132     my $path = shift;
       
   133 
       
   134     if (!$path || shift) {
       
   135         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
       
   136     }
       
   137 
       
   138     my ($exportRestricted, $errors) = $self->GetRequestedInformation($path, 'ExportRestricted');
       
   139 
       
   140     return ($exportRestricted, $errors);
       
   141 }
       
   142 
       
   143 sub GetRequestedInformation {
       
   144     my $self = shift;
       
   145     my $path = shift;
       
   146     my $what = shift;
       
   147 
       
   148     my @errors; # This collects the errors produced from the distribution policy modules.
       
   149                 # The CBR Tools handle these errors in a different way.
       
   150 
       
   151     if (!$path || !$what || shift) {
       
   152         croak "Invalid number of arguments passed to " . (caller(0))[3] . "\n";
       
   153     }
       
   154     
       
   155     my $result = undef;
       
   156     my $informationFrom = undef;
       
   157     
       
   158     if (!$self->{useDistPolFirst} && $self->{mrpObject}) {
       
   159         # If to use MRP files first and an Mrp object exists...
       
   160         $result = $self->{mrpObject}->$what($path);
       
   161 
       
   162         $informationFrom = 'M' if (defined $result);
       
   163     }
       
   164     
       
   165     if (! defined $result) {
       
   166         # If  distribution policies are to be used first or could not obtain information
       
   167         # from MRP object then use distribution policies
       
   168 
       
   169         # Create a distribution policy reader if one does not already exist...
       
   170         if (!$self->{distPolReader}) {
       
   171             # Create a distribution policy reader if one does not already exist...
       
   172             $self->{distPolReader} = Symbian::DistributionPolicy::Reader->new();
       
   173         }
       
   174         
       
   175         if ($self->{distPolReader}->isa("Symbian::DistributionPolicy::Reader")) {
       
   176             my $warner;
       
   177             
       
   178             # We may need to capture the output of the distribution policy modules
       
   179             if ($self->{'captureDistributionPolicyOutput'}) {
       
   180                 $warner = sub { push @errors, shift; };
       
   181             }
       
   182             local $SIG{__WARN__} = $warner if ($warner);
       
   183 
       
   184             # We want to make sure that we do have a reader before trying to read a file
       
   185             eval {  my $distPolObj = $self->{distPolReader}->ReadPolicyFile($path);
       
   186                     $result = $distPolObj->$what()};
       
   187 
       
   188             $informationFrom = 'D' if (defined $result);
       
   189         }
       
   190     }
       
   191 
       
   192     if ((!defined $result) && $self->{useDistPolFirst}) {
       
   193         # If distribution policies have been used first and failed then try getting the information from MRP files...
       
   194         
       
   195         # The Symbian::CBR::IPR::MRP might not yet have been created
       
   196         if (!exists $self->{mrpObject}) {
       
   197             $self->CreateMrpObject();
       
   198         }
       
   199         
       
   200         $result = $self->{mrpObject}->$what($path);
       
   201 
       
   202         $informationFrom = 'M' if (defined $result);
       
   203     }
       
   204    
       
   205     if (!defined $informationFrom && $self->{disallowUnclassifiedSource}) {
       
   206         carp "Warning: IPR information for '$path' could not be obtained from either MRP files or distribution policy files\n";
       
   207     }
       
   208         
       
   209     if ($self->{verbose} > 1) {
       
   210         # If verbose then we print information saying where the IPR information was obtained from
       
   211         if ($informationFrom eq 'M') {
       
   212             print "Info: IPR information for '$path' was obtained using MRP files\n";
       
   213         }
       
   214         elsif ($informationFrom eq 'D') {
       
   215             print "Info: IPR information for '$path' was obtained using Distribution Policy files\n";
       
   216         }        
       
   217     }
       
   218 
       
   219     return ($result, \@errors);
       
   220 }
       
   221 
       
   222 1;
       
   223 
       
   224 __END__
       
   225 
       
   226 =pod
       
   227 
       
   228 =head1 NAME
       
   229 
       
   230 Symbian::IPR - An interface to IPR information within MRP files and Distribution
       
   231 Policy files.
       
   232 
       
   233 =head1 SYNOPSIS
       
   234 
       
   235 use Symbian::IPR;
       
   236 
       
   237  # Instantiate a Symbian::IPR object
       
   238  my $iprObject = Symbian::IPR->instance(0, 0, 'MRP', undef, 1);
       
   239 
       
   240  # Get the IPR category for a path
       
   241  my $category = $iprObject->Category('\aPath\somewhere');
       
   242 
       
   243  # Get the export restricted flag for a path
       
   244  my $exportRestricted = $iprObject->ExportRestricted('\aPath\somewhere');
       
   245 
       
   246 =head1 DESCRIPTION
       
   247 
       
   248 This package provides an interface to obtaining IPR information from MRP files
       
   249 and Distribution Policy files.  The user can specify the order of preference
       
   250 between MRP and distribution policies.  If the requested information can not be
       
   251 obtained from the preferred choice then the package will fall back to using the
       
   252 other option.
       
   253 
       
   254 =head1 METHODS
       
   255 
       
   256 =head2 new(useDistPolFirst, disallowUnclassifiedSource, typeOfMrp, component, verbose)
       
   257 
       
   258 Instantiates a Symbian::IPR object.
       
   259 
       
   260 The default order is for IPR information to be obtained from MRP files first, and
       
   261 if unsuccessful then to obtain the IPR information from distribution policy files.
       
   262 If the boolean value useDistPolFirst is specified then IPR information will be
       
   263 obtained from distribution policy files by default, and if not successful then
       
   264 MRP files will be used.
       
   265 
       
   266 If the disallowUnclassifiedSource flag is specified then warnings will be produced
       
   267 if IPR information can not be obtained both MRP files and distribution.policy files.
       
   268 
       
   269 The typeOfMrp argument is non-optional.  Valid types are MRP and MRPDATA.  See the
       
   270 documentation for Symbian::CBR::MRP::Reader for more information.
       
   271 
       
   272 If a component had been specified then the MRP file for the component will be processed
       
   273 and the IPR information obtained.  Any MRP files for dependant components will be
       
   274 located and processed too.  If no component name has been specified all MRP files
       
   275 in the environment will be processed.
       
   276 
       
   277 =head2 Category(path)
       
   278 
       
   279 Returns the IPR category of the path.  If no IPR information exists for the
       
   280 specified path then X will be returned.
       
   281 
       
   282 =head2 ExportRestricted(path)
       
   283 
       
   284 Returns true if the specified path is export restricted, and false if it is not.
       
   285 If no IPR information exists for the specified path then undef will be returned.
       
   286 
       
   287 =head2 PrepareInformationForComponent(component_name)
       
   288 
       
   289 If using MRP files for IPR information it is possible to specify which components
       
   290 contain the information required.  This improves performance as only required
       
   291 MRP files are processed.  The default behaviour is to process all MRP files listed
       
   292 in the CBR Tools environment database.
       
   293 
       
   294 If using distribution policy files as default then information passed to this method
       
   295 will be cached and realised only if it becomes necessary to use MRP files for IPR
       
   296 information (e.g. distribution policy file does not exist).
       
   297 
       
   298 =head2 PrepareInformationForMrpFile(list_of_mrp_files)
       
   299 
       
   300 If using MRP files for IPR information it is possible to specify which MRP files
       
   301 contain the information required.  This can be used in scenarios where a CBR Tools
       
   302 environment database does not exist, and so MRP locations are unknown.
       
   303 
       
   304 If using distribution policy files as default then information passed to this method
       
   305 will be cached and realised only if it becomes necessary to use MRP files for IPR
       
   306 information (e.g. distribution policy file does not exist).
       
   307 
       
   308 =head1 COPYRIGHT
       
   309 
       
   310  Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
       
   311  All rights reserved.
       
   312  This component and the accompanying materials are made available
       
   313  under the terms of the License "Eclipse Public License v1.0"
       
   314  which accompanies this distribution, and is available
       
   315  at the URL "http://www.eclipse.org/legal/epl-v10.html".
       
   316  
       
   317  Initial Contributors:
       
   318  Nokia Corporation - initial contribution.
       
   319  
       
   320  Contributors:
       
   321  
       
   322  Description:
       
   323  
       
   324 
       
   325 =cut