#

# CDDL HEADER START

#

# The contents of this file are subject to the terms of the

# Common Development and Distribution License (the "License").

# You may not use this file except in compliance with the License.

#

# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

# or http://www.opensolaris.org/os/licensing.

# See the License for the specific language governing permissions

# and limitations under the License.

#

# When distributing Covered Code, include this CDDL HEADER in each

# file and include the License file at usr/src/OPENSOLARIS.LICENSE.

# If applicable, add the following below this CDDL HEADER, with the

# fields enclosed by brackets "[]" replaced with your own identifying

# information: Portions Copyright [yyyy] [name of copyright owner]

#

# CDDL HEADER END

#

# =============================================================================

# =============================================================================

"""

Module to validate defaults and contents info.

"""

# =============================================================================

# =============================================================================

import sys

import subprocess

from osol_install.TreeAcc import TreeAcc

from osol_install.TreeAcc import TreeAccNode

from osol_install.TreeAcc import TreeAccError

from osol_install.install_utils import canaccess

from osol_install.install_utils import space_parse

# =============================================================================

# Constants

# =============================================================================

# Error status

GENERAL_ERR = 1

SUCCESS = 0

# XML validator program, run on XML docs to validate against a schema.

XML_REFORMAT_SW = "--format"

# Defaults and validation manifest doc and schema filenames.

DEFVAL_SCHEMA = "/usr/share/lib/xml/rng/defval-manifest.rng "

# Schema to validate manifest XML doc against.

MANIFEST_SCHEMA = "/usr/lib/python2.6/vendor-packages/osol_install/" + \

                  "distro_const/DC-manifest.rng "

# Default XML value if invert isn't specified in the defval-manifest.

DEFAULT_INVERT_VALUE_STR = "False"

# =============================================================================

# General module initializion code

# =============================================================================

DEFAULT_INVERT_VALUE = (DEFAULT_INVERT_VALUE_STR == "True")

# =============================================================================

# Error handling classes

# =============================================================================

class ManifestProcError(StandardError):

    """Exception for manifest_proc errors"""

    pass

# =============================================================================

class _HelperDicts:

# =============================================================================

    """ Class of objects containing modules, methods and optionally invert

        statuses indexed by a reference (ref) string.

    These objects contain dictionaries which allow a module, method and

    invert status combination to be referenced by a common string.

    """

# =============================================================================

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    def __init__(self, module_dict, method_dict, invert_dict=None):

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        """ Constructor

        Args:

          module_dict: Dictionary of modules indexed by a ref string

          method_dict: Dictionary of methods indexed by a ref string

          invert_dict: Optional dictionary of boolean invert statuses

            indexed by a ref string

        Raises: None

        """

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        self.modules = module_dict

        self.methods = method_dict

        self.inverts = invert_dict

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    @staticmethod

    def new(defval_tree, nodepath):

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        """ Return a new helper object containing modules and methods

            indexed by a reference (ref) string.

        Args:

          defval_tree: Tree of defaults and validation nodes (TreeAccNodes)

            containing the information.  This tree has been read in from the

            defval manifest and contains references to the validator and default

            setter methods and their host modules.  It is assumed that the

            methods are part of a class of the same name as their host module.

          nodepath: Root of tree branch containing information on helper

            methods of interest.  For example, the part of the tree

            containing validator methods or the part containing

            methods filling in defaults.

        Returns:

          If information is found under "nodepath" in the defval_tree:

            returns a new helper object containing dictionaries for

            module and method.  Both dictionaries are indexed by a

            ref string.

          Otherwise returns an object with empty module and method dicts

        Raises:

          ManifestProcError: Helper ref (index string) is not unique

          ManifestProcError: Invalid python helper module name

          ImportError: Helper module cannot be imported

        """

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

        modules = {}	# Dict of modules indexed by ref

        methods = {}	# Dict of methods indexed by ref

        inverts = {}	# Dict of boolean invert statuses indexed by ref

        class_names = {}	# Used for internal processing

        # Extract helpers from the tree.

        helpers = defval_tree.find_node(nodepath)

        if (len(helpers) == 0):

            return _HelperDicts(modules, methods, None)

        # Each helper element contains attributes for module, method

        # and ref.

        for helper in helpers:

            # Get list of attributes for current helper element.

            helper_attrs = helper.get_attr_dict()

            # This is the ref string used to index into the

            # dictionaries for a given method in a given module.

            ref = helper_attrs["ref"]

            # Make sure the helper ref is unique.

            if ref in methods:

                raise ManifestProcError, ("HelperDicts.new: helper ref " +

                                          ref + " is not unique")

            # Get and validate module name.

            module_name = helper_attrs["module"]

            if not module_name.endswith(".py"):

                raise ManifestProcError, ("HelperDicts.new: Invalid python " +

                                         "helper module name: " + module_name)

            # Assume class is same name as the module it's in.

            class_name = module_name[:-3]

            # Maintain a list of class names.  This list is used

            # to prevent multiple compilations of the same module.

            # Search list of class names for a match.  If a match

            # is found, refer to the corresponding module instance

            # instead of creating a new one.

            for key, name in class_names.items():

                if (class_name == name):

                    modules[ref] = modules[key]

                    break

            # Note: in trouble if rename helper_module to

            # helpers.  (Maybe can use local_dicts?)

            # Module not in list.

            else:

                # Add name to the list and compile the module.

                class_names[ref] = class_name

                # Import the module.

                # The ugly-looking rfind below strips all to

                # the left of the final dot (e.g package names).

                # __import__ returns package, not module, unless a method

                # name is given as fourth arg.

                constr_name = class_name[(class_name.rfind(".") + 1):]

                module_imp = __import__(class_name, globals(), locals(),

                                        [constr_name], -1)

                # Instantiate and save a module instance.

                constr = getattr(module_imp,

                                 class_name[(class_name.rfind(".") + 1):])

                modules[ref] = constr()

            # Save the method in the instance's methods dictionary.

            methods[ref] = helper_attrs["method"]

            # Save invert status in instance's inverts dictionary.

            # If not specified, assume DEFAULT_INVERT_VALUE_STR.

            try:

                ivalue = helper_attrs["invert"]

            except KeyError:

                ivalue = DEFAULT_INVERT_VALUE_STR

            inverts[ref] = (ivalue == "True")

        # If all inverts values are the default, it may be that this

        # HelperDict is not for validation and inverts aren't used.

        # Optimize that if all invert values are the default, don't

        # store inverts in this _HelperDicts instance.

        keep_inverts = False

        for ivalue in inverts.itervalues():

            if (ivalue != DEFAULT_INVERT_VALUE):

                keep_inverts = True

                break

        if (not keep_inverts):

            inverts = None

        return _HelperDicts(modules, methods, inverts)

# =============================================================================

# Procedural functions, not part of a class

# =============================================================================

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    """ Validate an XML document against a schema.

    Runs the command given by XML_VALIDATOR.  Schema must follow the

    XML_VALIDATOR string.  If out_xml_doc is specified, reformat the

    xml doc  using the XML_REFORMAT_SW passed to the validator.

    Args:

      schema: The schema to validate against.

      in_xml_doc: The XML document to validate.

      out_xml_doc: Reformatted XML doc

    Returns: N/A

    Raises:

      OSError: Error starting or running shell

      ManifestProcError: The validator returned an error status or

        was terminated by a signal.

    """

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    schema = schema.strip()

    in_xml_doc = in_xml_doc.strip()

    # Need to check file access explicitly since the XML

    # validator doesn't return proper errno if files not accessible.

    # IOError exceptions (from canaccess()) require no special

    # handling here, except for closing outfile.

    # Just let IOErrors get thrown and propagated.

    canaccess(schema, "r")

    canaccess(in_xml_doc, "r")

    if (out_xml_doc is not None):

        command_list.append(XML_REFORMAT_SW)

        outfile = file(out_xml_doc.strip(), "w")

    else:

        outfile = file("/dev/null", "w")

    command_list.append(in_xml_doc)

    try:

        try:

            rval = subprocess.Popen(command_list, stdout=outfile).wait()

            if (rval < 0):

                print >> sys.stderr, ("validate_vs_schema: " +

                                      "Validator terminated by signal" +

                                      str(-rval))

            elif (rval > 0):

                print >> sys.stderr, ("validate_vs_schema: " +

                                      "Validator terminated with status " +

                                      str(rval))

            if (rval != 0):

                raise ManifestProcError, ("validate_vs_schema: " +

                                          "Validator terminated abnormally")

        # Print extra error message here for OSErrors as unexpected.

        except OSError:

            print >> sys.stderr, ("validate_vs_schema: " +

                                  "Error starting or running shell:")

            print >> sys.stderr, "shell_list = " + str(command_list)

            raise

    finally:

        outfile.close()

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

def __generate_ancestor_nodes(tree, nodepath):

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    """ Create ancestor nodes along given nodepath from root on down, as

        needed.

    Nodes created will have no value, and all but the last node created

    will have one child, the next node in the created nodepath.

    Nodepath is assumed to be from the tree root and deterministic at each

    piece.  Since created nodepath is to a soon-to-be non-leaf node, all

    nodepath items created will be elements.

    Args:

      tree: Tree in which the nodes are created.

      nodepath: Path defining where nodes are created in the tree.

    Returns:

      The node created furthest from the root.

    Raises:

      ManifestProcError: non-deterministic nodepath specified.

    """

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    nodepath_pieces = nodepath.split("/")

    # Note current_node starts out and remains a one-item list.

    ancestor_node = current_node = tree.find_node(nodepath_pieces[0])

    # Err out if the nodepath (from the defval manifest) doesn't jibe

    # with the project manifest.  At a minimum, the tops of the trees

    # should be the same.

    if (len(ancestor_node) == 0):

        raise ManifestProcError, ("generate_ancestor_nodes: " +

                                  "manifest and defval manifest " +

                                  "are incompatible")

    # Iterate from the top of the nodepath, filling in nodes which are

    # missing.  New nodes will have no value.

    for i in range(1, len(nodepath_pieces)):

        current_node = tree.find_node(nodepath_pieces[i],

                                      ancestor_node[0])

        # Add missing ancestor node.

        if (len(current_node) == 0):

            new_node = tree.add_node(nodepath_pieces[i], "",

                                     TreeAccNode.ELEMENT, ancestor_node[0])

            current_node = [new_node]

        elif (len(current_node) > 1):

            raise ManifestProcError, ("generate_ancestor_nodes: " +

                                      "non-deterministic nodepath specified")

        ancestor_node = current_node

    return current_node

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

def __get_value_from_helper(method_ref, deflt_setter_dicts,

                            parent_node, debug):

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    """ Consult a helper method to calculate/retrieve a value.

    Args:

      method_ref: Nickname reference of the helper method to call.

      deflt_setter_dicts: _HelperDicts object containing helper information

      parent_node: Parent node of the new node (for whose value the helper

        is being consulted).  The helper method will be called with

        this node, from which it can get a pointer to the tree as well

        as context to perform its calculation.

      debug: Print tracing / debug messages when True

    Returns:

      A string representation of the value as returned by the helper method.

          Convert any python boolean value strings to all-lowercase, to

        match how booleans are represented in XML documents.

    Raises:

      ManifestProcError: Helper method missing from defval manifest file

      AttributeError: Helper method is not in module

      StandardError: Helper method raised an exception

    """

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    if ((method_ref not in deflt_setter_dicts.modules) or

        (method_ref not in deflt_setter_dicts.methods)):

        raise ManifestProcError, ("get_value_from_helper: Helper method " +

                                  "ref %s missing from defval manifest file" %

                                  method_ref)

    module = deflt_setter_dicts.modules[method_ref]

    method = deflt_setter_dicts.methods[method_ref]

    if (debug):

        print ("Call helper method " +

               deflt_setter_dicts.methods[method_ref] + "()")

    # Note: methods calculating defaults take only the parent node as arg.

    try:

        func = getattr(module, method)

    except AttributeError:

        print >> sys.stderr, ("get_value_from_helper: Helper method " +

                              "%s not in module %s" % (method, module))

        raise

    try:

        value = func(parent_node)

    except StandardError:

        print >> sys.stderr, ("get_value_from_helper: Helper method " +

                                  "%s raised an exception: " % method_ref)

        raise

    # Convert all return values to strings.

    #

    # Booleans are a special case.  Python boolean values (and their string

    # equivalents when converted) begin with capital letters.  However, XML

    # boolean string values are all in lower case.

    if (isinstance(value, bool)):

        retvalue = str(value).lower()

    else:

        retvalue = str(value)

    return retvalue

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

def __do_skip_if_no_exist(attributes, manifest_tree, debug):

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    """ Determines whether or not to skip processing of a node because an

        ancestral node to it doesn't exist.

    Check if the "skip_if_no_exist" attribute exists in the attributes

    list passed in.  If it does, and if the (ancestral) node it refers to

    doesn't exist in manifest_tree, then return True, that it's OK to skip

    creating/processing.

    Args:

      attributes: Attributes list to check for skip_if_no_exist in.

      manifest_tree: tree to search for the node identified by the

        skip_if_no_exist attribute.

      debug: Print tracing / debug messages when True

    Returns:

      True: skip_if_no_exist attribute exists and identifies a node which

        doesn't exist.

      False: otherwise

    Raises: None

    """

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    skip_if_no_exist = attributes.get("skip_if_no_exist", "")

    if (skip_if_no_exist != ""):

        if (debug):

            print ("Skip_if_no_exist = %s specified.  checking" %

                   skip_if_no_exist)

        if (len(manifest_tree.find_node(skip_if_no_exist)) == 0):