#
# Copyright (c) 2015 NetApp, Inc., All Rights Reserved.
#   Any other use, modification, or distribution is prohibited
#   without prior written consent from NetApp, Inc.
#

## @pod here
## @author dl-nacl-dev@netapp.com
## @summary The ServiceAPI for NACL::Service::Xgen

package NACL::ServiceAPI::Xgen;

use strict;
use warnings;

use parent qw( NACL::ServiceAPI );

use NATE::Log qw(log_global);

use NACL::Service::Xgen::Resource;

my $Log = log_global();
my $may_enter = $Log->may_enter();
my $may_exit  = $Log->may_exit();

sub new {
    my ($class, %opts) = @_;
    return $class->SUPER::new(%opts,
                              _generate_methods => 0,
                              service_class => "NACL::Service::Xgen");
}

sub build_config {
    my ($self, %args) = @_;
    $Log->enter() if $may_enter;

    my $client_formatter_module = delete($args{client_formatter_module});
    my $formatter_obj;

    if (defined($client_formatter_module)) {
        my $client_formatter_path = $client_formatter_module;

        $client_formatter_path =~ s/::/\//g;
        $client_formatter_path .= '.pm';
        require $client_formatter_path;

        # create formatter object
        $formatter_obj = $client_formatter_module->new(%args);
    }

    # execute the build config API on the service
    my $resource_hash_ref =
        $self->_core_client_api(_api            => 'build_config',
                                request_timeout => -1,
                                _namespace      => "NACL::Service::Xgen",
                                %args);

    # walk each resource type and apply the formatter
    foreach my $resource_type (keys(%{$resource_hash_ref})) {
        # require $resource_type_path for rebless
        my $resource_type_path = $resource_type;
        $resource_type_path =~ s/::/\//g;
        $resource_type_path .= '.pm';
        require $resource_type_path;

        @{$resource_hash_ref->{$resource_type}} = map {
            my $resource = $_;
            my $resource_obj =
                NACL::Service::Xgen::Resource->rebless_resource(resource_type => $resource_type,
                                                                resource      => $resource);
            if (defined($client_formatter_module)) {
                $resource_obj->to_format(formatter => $formatter_obj);
            }
            $resource_obj; # last line gets stored in $_
        } @{$resource_hash_ref->{$resource_type}};
    }

    # run formatter against entire resource list
    if (defined($client_formatter_module)) {
        $Log->exit() if $may_exit;
        return $formatter_obj->apply_format_to_resource_list($resource_hash_ref);
    } else {
        $Log->exit() if $may_exit;
        return $resource_hash_ref;
    }
}

1;

=pod

=head1 NAME

NACL::ServiceAPI::Xgen

=head1 SYNOPSIS

 use NACL::ServiceAPI::Xgen;

=head1 DESCRIPTION

C<NACL::ServiceAPI::Xgen> is used to communicate and control the L<C<NACL::Service::Xgen>|lib-NACL-Service-Xgen-pm> Service. Xgen is a
configuration service that is capable of building out resource lists. Resource lists are then typically used by
dispatcher libraries/frameworks to build out these configurations. For more information on developing
backend components that leverage the Xgen framework. See the Xgen Service libraries:

=over

=item L<C<NACL::Service::Xgen>|lib-NACL-Service-Xgen-pm>

=item L<C<NACL::Service::Xgen::Config>|lib-NACL-Service-Xgen-Config-pm>

=item L<C<NACL::Service::Xgen::Resource>|lib-NACL-Service-Xgen-Resource-pm>

=item L<C<NACL::Service::Xgen::Formatter>|lib-NACL-Service-Xgen-Formatter-pm>

=back

=head1 METHODS

=head2 new

This is the constructor that discovers a running C<NACL::Service::Xgen> service or starts a new one if it has not
started yet.

=over

=item Synopsis

  use NACL::ServiceAPI::Xgen;
  my $api = NACL::ServiceAPI::Xgen->new();

=back

=head2 build_config

This API will build the specified configuration module. Configuration modules are derived classes of L<C<NACL::Service::Xgen::Config>|lib-NACL-Service-Xgen-Config-pm>.
This method will return back a hash reference datastructure of all the resources that define the configuration specified.
Formatter libraries (derived classes of L<C<NACL::Service::Xgen::Formatter>|lib-NACL-Service-Xgen-Formatter-pm>) can be provided that will
perform additional translation processing of the resource list after it gets built by the configuration module.

=over

=item Synopsis

    use NACL::ServiceAPI::Xgen;
    my $api = NACL::ServiceAPI::Xgen->new();

    # create a resource list defined by a specific Xgen Configuration Module
    my $resource_list = $api->build_config(config_module => "My::Xgen::Config::Module",
                                           %passthrough_key_value_pairs);

    # create a resource list defined by a specific Xgen Configuration Module but have it
    # prefer a resource list that has been cached by a prior invocation
    my $resource_list = $api->build_config(config_module => "My::Xgen::Config::Module",
                                           use_cached_config => 1);

    # create a resource list defined by a specific Xgen Configuration Module and
    # have it be processed by a client side formatter module.
    my $formatted_resource_list = $api->build_config(config_module => "My::Xgen::Config::Module",
                                                     client_formatter_module => "My::Xgen::Formatter::Module");


=item Arguments

=over

=item C<< config_module => $scalar >>

(Required) This is the configuration module to build. The configuration module must be a derived class
of L<C<NACL::Service::Xgen::Config>|lib-NACL-Service-Xgen-Config-pm>, directly or indirectly. The Xgen service will instantiate and invoke
the C<build> method defined in the configuration module. If successful, a resource list will be returned
to the caller.

=item C<< display_config => 0|1|2 >>

(Optional) If enabled, the Xgen service will display a summary of the resource list if it
was successful. Set to 0 to disable. Set to 1 to enable a brief summary. Set to 2 to enable a verbose summary.

Default: 0 (no summary)

=item C<< use_cached_config => 0|1 >>

(Optional) If enabled, the Xgen service will attempt to obtain a cached version of this configuration
that may have been built in the past. If it cannot be obtained from the cache, a new one will be generated,
and returned. By default, all resource lists successfully generated by C<build_config> will be cached.

Default: 0

=item C<< random_seed => $scalar >>

(Optional) If specified, a seed can be installed prior to building the configuration. This allows you
to ensure that if the configuration module is attempting to define any randomness to the configuration,
that it can be repeatable.

Default: "fixed_seed"

=item C<< client_formatter_module => $scalar >>

(Optional) If provided, the configuration resource list will be fed into this formatter module
prior to the resource list being returned by this method. This formatter will be processed
client-side. Formatter modules are derived classes of L<C<NACL::Service::Xgen::Formatter>|lib-NACL-Service-Xgen-Formatter-pm> and
are typically used if you want to translate the resource list that gets built into something
that a resource provisioning dispatch tool or library can understand and parse.

Default: undef

=item C<< service_formatter_module => $scalar >>

(Optional) If provided, the configuration resource list will be fed into this formatter module
prior to the resource list being sent back to the client API. This formatter will be processed
service-side as opposed to client-side. By default the service will use
the L<C<NACL::Service::Xgen::Formatter>|lib-NACL-Service-Xgen-Formatter-pm> base class to handle this operation. Typically this
parameter need not be modified.

Default: "NACL::Service::Xgen::Formatter"

=item C<< %passthrough_key_value_pairs >>

(Optional) Any parameters that need to be passed into the C<build> method implemented in
the configuration module specified by C<config_module> can be defined here as passthrough parameters.

=back

=back

=head1 SEE ALSO

This is a derived class of L<C<NACL::ServiceAPI>|lib-NACL-ServiceAPI-pm>. Please see that module's documentation for more details.

=head1 AUTHOR/MAINTAINER

=over

=item NACL Development (dl-nacl-dev@netapp.com)

=back

=cut