#!/usr/bin/python2.4

#

# 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

#

#

# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.

# Use is subject to license terms.

#

import copy

import os

import simplejson as json

import StringIO

import sys

import urllib

import urllib2

import pkg.client.actuator as actuator

import pkg.client.api_errors as api_errors

import pkg.client.bootenv as bootenv

import pkg.client.history as history

import pkg.client.image as image

import pkg.client.indexer as indexer

import pkg.client.publisher as publisher

import pkg.client.query_parser as query_p

import pkg.fmri as fmri

import pkg.misc as misc

import pkg.p5i as p5i

import pkg.search_errors as search_errors

import pkg.variant as variant

import pkg.nrlock

from pkg.client.imageplan import EXECUTED_OK

from pkg.client import global_settings

CURRENT_API_VERSION = 20

CURRENT_P5I_VERSION = 1

class ImageInterface(object):

        """This class presents an interface to images that clients may use.

        There is a specific order of methods which must be used to install

        or uninstall packages, or update an image. First, plan_install,

        plan_uninstall, plan_update_all or plan_change_variant must be

        called.  After that method completes successfully, describe may be

        called, and prepare must be called. Finally, execute_plan may be

        called to implement the previous created plan. The other methods

        do not have an ordering imposed upon them, and may be used as

        needed. Cancel may only be invoked while a cancelable method is

        running."""

        # Constants used to reference specific values that info can return.

        INFO_FOUND = 0

        INFO_MISSING = 1

        INFO_MULTI_MATCH = 2

        INFO_ILLEGALS = 3

        # Private constants used for tracking which type of plan was made.

        __INSTALL = 1

        __UNINSTALL = 2

        __IMAGE_UPDATE = 3

        def __init__(self, img_path, version_id, progesstracker,

            cancel_state_callable, pkg_client_name):

                """Constructs an ImageInterface. img_path should point to an

                existing image. version_id indicates the version of the api

                the client is expecting to use. progesstracker is the

                progresstracker the client wants the api to use for UI

                callbacks. cancel_state_callable is a function which the client

                wishes to have called each time whether the operation can be

                canceled changes. It can raise VersionException and

                ImageNotFoundException."""

                compatible_versions = set([19, 20])

                if version_id not in compatible_versions:

                        raise api_errors.VersionException(CURRENT_API_VERSION,

                            version_id)

                # The image's History object will use client_name from

                # global_settings, but if the program forgot to set it,

                # we'll go ahead and do so here.

                if global_settings.client_name is None:

                        global_settings.client_name = pkg_client_name

                # Store this for reset().

                self.__img_path = img_path

                self.__img = image.Image()

                self.__img.find_root(img_path)

                self.__img.load_config()

                self.__progresstracker = progesstracker

                self.__cancel_state_callable = cancel_state_callable

                self.__plan_type = None

                self.__plan_desc = None

                self.__prepared = False

                self.__executed = False

                self.__be_name = None

                self.__can_be_canceled = False

                self.__canceling = False

                self.__activity_lock = pkg.nrlock.NRLock()

        @property

        def img(self):

                """Private; public access to this property will be removed at

                a later date.  Do not use."""

                return self.__img

        @property

        def root(self):

                """The absolute pathname of the filesystem root of the image.

                This property is read-only."""

                if not self.__img:

                        return None

                return self.__img.root

        @staticmethod

        def check_be_name(be_name):

                bootenv.BootEnv.check_be_name(be_name)

                return True

        def __cert_verify(self, log_op_end=None):

                """Verify validity of certificates.  Any

                api_errors.ExpiringCertificate exceptions are caught

                here, a message is displayed, and execution continues.

                All other exceptions will be passed to the calling

                context.  The caller can also set log_op_end to a list

                of exceptions that should result in a call to

                self.log_operation_end() before the exception is passed

                on."""

                if log_op_end == None:

                        log_op_end = []

                # we always explicitly handle api_errors.ExpiringCertificate

                assert api_errors.ExpiringCertificate not in log_op_end

                try:

                        self.__img.check_cert_validity()

                except api_errors.ExpiringCertificate, e:

                        misc.emsg(e)

                except:

                        exc_type, exc_value, exc_traceback = sys.exc_info()

                        if exc_type in log_op_end:

                                self.log_operation_end(error=exc_value)

                        raise

        def __load_catalog(self, refresh_catalogs=True, manual_load=True):

                """Refresh and load catalogs, or load the old on-disk

                catalogs."""

                #

                # Verify validity of certificates before possibly

                # attempting network operations.

                #

                self.__cert_verify()

                if refresh_catalogs:

                        try:

                                self.__img.refresh_publishers(

                                    progtrack=self.__progresstracker)

                        except KeyboardInterrupt:

                                raise

                        except api_errors.InvalidDepotResponseException:

                                raise

                        except:

                                # Since this is not a refresh

                                # that was explicitly requested,

                                # it doesn't matter if it fails.

                                pass

                elif manual_load:

                        # If refresh wasn't called, the catalogs

                        # have to be manually loaded.

                        self.__img.load_catalogs(self.__progresstracker)

        def __plan_common_start(self, operation):

                """Start planning an operation.  Aquire locks and log

                the start of the operation."""

                self.__activity_lock.acquire()

                try:

                        self.__set_can_be_canceled(True)

                        if self.__plan_type is not None:

                                raise api_errors.PlanExistsException(

                                    self.__plan_type)

                except:

                        self.__activity_lock.release()

                        raise

                assert self.__activity_lock._is_owned()

                self.log_operation_start(operation)

        def __plan_common_finish(self):

                """Finish planning an operation."""

                assert self.__activity_lock._is_owned()

                self.__activity_lock.release()

        def __plan_common_exception(self, log_op_end=None):

                """Deal with exceptions that can occur while planning an

                operation.  Any exceptions generated here are passed

                onto the calling context.  By default all exceptions

                will result in a call to self.log_operation_end() before

                they are passed onto the calling context.  Optionally,

                the caller can specify the exceptions that should result

                in a call to self.log_operation_end() by setting

                log_op_end."""

                if log_op_end == None:

                        log_op_end = []

                # we always explicity handle api_errors.PlanCreationException

                assert api_errors.PlanCreationException not in log_op_end

                exc_type, exc_value, exc_traceback = sys.exc_info()

                if exc_type == api_errors.PlanCreationException:

                        self.__set_history_PlanCreationException(exc_value)

                        self.log_operation_end(error=exc_value)

                raise

        def plan_install(self, pkg_list, filters, refresh_catalogs=True,

            noexecute=False, verbose=False, update_index=True):

                """Contructs a plan to install the packages provided in

                pkg_list.  pkg_list is a list of packages to install.  filters

                is a list of filters to apply to the actions of the installed

                packages.  refresh_catalogs controls whether the catalogs will

                automatically be refreshed. noexecute determines whether the

                history will be recorded after planning is finished.  verbose

                controls whether verbose debugging output will be printed to the

                terminal.  Its existence is temporary.  It returns a boolean

                which tells the client whether there is anything to do.  It can

                raise PlanCreationException, PermissionsException and

                InventoryException. The noexecute argument is included for

                compatibility with operational history.  The hope is it can be

                removed in the future."""

                self.__plan_common_start("install")

                try:

                        self.__load_catalog(refresh_catalogs, manual_load=False)

                        self.__img.make_install_plan(pkg_list,

                            self.__progresstracker,

                            self.__check_cancelation, noexecute,

                            filters=filters, verbose=verbose)

                        assert self.__img.imageplan

                        if self.__canceling:

                                raise api_errors.CanceledException()

                        self.__set_can_be_canceled(False)

                        if not noexecute:

                                self.__plan_type = self.__INSTALL

                        self.__plan_desc = PlanDescription(self.__img.imageplan)

                        if self.__img.imageplan.nothingtodo() or noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        self.__img.imageplan.update_index = update_index

                except:

                        self.__plan_common_exception(log_op_end=[

                            api_errors.CanceledException, fmri.IllegalFmri,

                            Exception])

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res

        def plan_uninstall(self, pkg_list, recursive_removal, noexecute=False,

            verbose=False, update_index=True):

                """Contructs a plan to uninstall the packages provided in

                pkg_list. pkg_list is a list of packages to install.

                recursive_removal controls whether recursive removal is

                allowed. noexecute determines whether the history will be

                recorded after planning is finished. verbose controls whether

                verbose debugging output will be printed to the terminal. Its

                existence is temporary. If there are things to do to complete

                the uninstall, it returns True, otherwise it returns False. It

                can raise NonLeafPackageException and PlanCreationException."""

                self.__plan_common_start("uninstall")

                try:

                        self.__img.make_uninstall_plan(pkg_list,

                            recursive_removal, self.__progresstracker,

                            self.__check_cancelation, noexecute,

                            verbose=verbose)

                        assert self.__img.imageplan

                        if self.__canceling:

                                raise api_errors.CanceledException()

                        self.__set_can_be_canceled(False)

                        if not noexecute:

                                self.__plan_type = self.__UNINSTALL

                        self.__plan_desc = PlanDescription(self.__img.imageplan)

                        if noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        self.__img.imageplan.update_index = update_index

                except:

                        self.__plan_common_exception()

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res

        def plan_update_all(self, actual_cmd, refresh_catalogs=True,

            noexecute=False, force=False, verbose=False, update_index=True,

            be_name=None):

                """Creates a plan to update all packages on the system to the

                latest known versions.  actual_cmd is the command used to start

                the client.  It is used to determine the image to check whether

                SUNWipkg is up to date.  refresh_catalogs controls whether the

                catalogs will automatically be refreshed.  noexecute determines

                whether the history will be recorded after planning is finished.

                force controls whether update should proceed even if ipkg is not

                up to date.  verbose controls whether verbose debugging output

                will be printed to the terminal.  Its existence is temporary. It

                returns a tuple of two things.  The first is a boolean which

                tells the client whether there is anything to do.  The second

                tells whether the image is an opensolaris image.  It can raise

                CatalogRefreshException, IpkgOutOfDateException,

                PlanCreationException and PermissionsException."""

                self.__plan_common_start("image-update")

                try:

                        self.check_be_name(be_name)

                        self.__be_name = be_name

                        self.__load_catalog(refresh_catalogs)

                        # If we can find SUNWipkg and SUNWcs in the

                        # target image, then we assume this is a valid

                        # opensolaris image, and activate some

                        # special case behaviors.

                        opensolaris_image = True

                        fmris, notfound, illegals = \

                            self.__img.installed_fmris_from_args(

                                ["SUNWipkg", "SUNWcs"])

                        assert(len(illegals) == 0)

                        if notfound:

                                opensolaris_image = False

                        if opensolaris_image and not force:

                                try:

                                        if not self.__img.ipkg_is_up_to_date(

                                            actual_cmd,

                                            self.__check_cancelation,

                                            noexecute,

                                            refresh_allowed=refresh_catalogs,

                                            progtrack=self.__progresstracker):

                                                raise api_errors.IpkgOutOfDateException()

                                except api_errors.ImageNotFoundException:

                                        # Can't do anything in this

                                        # case; so proceed.

                                        pass

                        pkg_list = [

                            ipkg.get_pkg_stem()

                            for ipkg in self.__img.gen_installed_pkgs()

                        ]

                        self.__img.make_install_plan(pkg_list,

                            self.__progresstracker,

                            self.__check_cancelation,

                            noexecute, verbose=verbose,

                            multimatch_ignore=True)

                        assert self.__img.imageplan

                        if self.__canceling:

                                raise api_errors.CanceledException()

                        self.__set_can_be_canceled(False)

                        if not noexecute:

                                self.__plan_type = self.__IMAGE_UPDATE

                        self.__plan_desc = PlanDescription(self.__img.imageplan)

                        if self.__img.imageplan.nothingtodo() or noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        self.__img.imageplan.update_index = update_index

                except:

                        self.__plan_common_exception(

                            log_op_end=[api_errors.IpkgOutOfDateException])

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res, opensolaris_image

        def plan_change_variant(self, variants, noexecute=False,

            verbose=False, be_name=None):

                """Creates a plan to change the specified variants on an image.

                There is option to refresh_catalogs since if we're changing

                architectures, we have to download manifests that were

                previously uncached.  noexecute determines whether the history

                will be recorded after planning is finished.  verbose controls

                whether verbose debugging output will be printed to the

                terminal.  This function has two return values.  The first is

                a boolean which tells the client whether there is anything to

                do.  The third is either None, or an exception which indicates

                partial success.  This is currently used to indicate a failure

                in refreshing catalogs. It can raise CatalogRefreshException,

                IpkgOutOfDateException, NetworkUnavailableException,

                PlanCreationException and PermissionsException."""

                self.__plan_common_start("change-variant")

                try:

                        self.check_be_name(be_name)

                        self.be_name = be_name

                        self.__load_catalog(refresh_catalogs=True)

                        self.__img.image_change_variant(variants,

                            self.__progresstracker,

                            self.__check_cancelation,

                            noexecute, verbose=verbose)

                        assert self.__img.imageplan

                        if self.__canceling:

                                raise api_errors.CanceledException()

                        self.__set_can_be_canceled(False)

                        if not noexecute:

                                self.__plan_type = self.__IMAGE_UPDATE

                        self.plan_desc = PlanDescription(self.__img.imageplan)

                        if self.__img.imageplan.nothingtodo() or noexecute:

                                self.log_operation_end(

                                    result=history.RESULT_NOTHING_TO_DO)

                        #

                        # We always rebuild the search index after a

                        # variant change

                        #

                        self.__img.imageplan.update_index = True

                except:

                        self.__plan_common_exception()

                        # NOTREACHED

                self.__plan_common_finish()

                res = not self.__img.imageplan.nothingtodo()

                return res

        def describe(self):

                """Returns None if no plan is ready yet, otherwise returns

                a PlanDescription"""

                return self.__plan_desc

        def prepare(self):

                """Takes care of things which must be done before the plan

                can be executed. This includes downloading the packages to

                disk and preparing the indexes to be updated during

                execution. It can raise ProblematicPermissionsIndexException,

                and PlanMissingException. Should only be called once a

                plan_X method has been called."""

                self.__activity_lock.acquire()

                self.__set_can_be_canceled(True)