Brock, Please consider these initial comments. 1. I like the idea of an object-oriented API, i.e., a main object called Image (a noun describing what is being manipulated) as opposed to an API name like PkgClient. That's one thing that is nice about the API as it exists today. Is there a reason why the existing API can't just be enhanced?
2. One operation required by a GUI is the need to allow the user to accept a license. How would that be done using this API? Would action objects be exposed? The GUI must be able to download and get the text of the license so that it can be shown to the user. 3. Since a GUI displays a list of packages that the user can select, having the list operation is essential for the GUI. One of the key operations is taking entries from the list and passing them pack into the install operation. So it is hard to evaluate the install API without knowing what list is going to return. 4. A key question for this API, IMHO, is whether an image plan can exist independently from the image. Right now, the Image object has an imageplan member. However, another option is that one or more image plans could exist at any given time, with each of them pointing back at the image. This way, plan_install would return an image plan, and then one would do the prepare, execute, etc. on the image plan, not the image. I'm not sure what the use case would be for having multiple image plans active at one time, so maybe that is adding extra complexity to the API that shouldn't be there. 5. I don't think the term "Ipkg" should show up in the API (IpkgOutOfDateException) since that is just what the OpenSolaris package for this software happens to be called at this time. Thanks. Tom Brock Pytlik wrote: > Hi everyone, > > Here's a draft of the API that's been discussed previously. Please let > me know if there are capabilities not provided that the packamanger > needs that can't easily be handled by extending the progresstracker > class. The plan is to get the CLI working using the API and take the > feedback with the goal of having a fairly firm API in 3-4 weeks in the > gate that the GUI can integrate with. One thing that's still to come > from an API design perspective is to collect all the exceptions that > cross the API boundary together into a single module (or small number of > modules) so that they're accessible and easily tracked. > > To be clear, this is a draft. Names, functionality, and nearly anything > may change. Also, this version of the API is specifically for the most > dangerous operations, ones that can harm a users system: Install, > Uninstall, Image-Update, and Refresh. Others like list, search, info, > etc... will be added to this API in the future, but the first step is to > get the GUI and the CLI passing through the same interface on the > critical actions. > > The flow of control for the consumer of a PkgClient object is: > 1) Create an API object. This establishes which Image the API object is > associated with and assigns a progresstracker (for simplicity) > 2) Call either plan_install, plan_uninstall, plan_image_update > 3) Call prepare > 4) Call execute_plan > > Cancel essentially sends you back one step (so if it's doing 3 and > cancel is sent, the state will return to 2). > Reset returns the state to just after step 1. > > Thanks, > Brock > > class PkgClient(object): > def __init__(self, img_path, version_id, progesstracker, > cancel_state_callable): > # Raises VersionException, NoImageException > > def plan_install(self, pkg_list, filters): > # pkg_list: list of packages to install > # filters: filters to apply to the actions of the installed > # packages > # Returns 1 if it has things to do, 0 for nothing to be done > # Raises InvalidCertException, image.PlanCreationException, > # image.UnmatchedFmriException > > def plan_uninstall(self, pkg_list, recursive_removal): > # pkg_list: list of packages to remove > # recursive_removal: whether recursive removal should be > # applied > # Returns 1 if it has things to do, 0 for nothing to be done > # Raises imageplan.NonLeafPackageException, > # image.PlanCreationException > > def plan_update_all(self, actual_cmd): > # Returns a tuple of: > # whether there is anything to do, > # whether this is an opensolaris image, > # if an exception that was caught that allowed > # execution to continue, it is > # returned, otherwise None is > # returned > # raises image.CatalogRefreshException, > # IpkgOutOfDateException > # image.PlanCreationException > > def describe(self): > # Returns None if no plan is ready yet, otherwise returns > # a PlanDescription > > def prepare(self): > # Downloads the packages to disk. > # Prepares the indexes for updating. > # Raises search_errors.ProblematicPermissionsIndexException, > # UnknownPlanTypeException > > def execute_plan(self): > # Raises search_erorrs:(InconsistentIndexException, > # PartialIndexingException, > # ProblematicPermissionsIndexException) > # Raises ImageplanStateException > > def refresh(self, full_refresh, auths=None): > # full_refresh: whether to do a full retrieval of the > catalog > # from the authority or only update the existing catalog > # auths: a list of authorities to refresh. Passing an empty > # list or using the default value means to refresh all > # known authorities > > def can_be_cancelled(self): > # Returns true if the API is in a cancelable state. > > def reset(self): > # This resets the API object back to initial state > > def cancel(self): > # Used for asynchronous cancellation > # Puts the API back into the previous state. > # Canceling during a plan phase returns the > # API to its initial state. Cancelling > # during prepare puts the API into the > # state it was in just after planning had completed. > # Plan execution cannot be canceled. > > class PlanDescription(object): > def get_changes(self): > # Returns a list of (origin fmri string, destrination > fmri string) pairs > > Exceptions: > class ApiVersionException(Exception) > # Provides the expected and provided version > > class InvalidCertException(Exception) > # Raised when the client's certificate is not valid > > class ImageplanStateException(Exception) > # Raised when plan execution did not complete > # Provides the last good state of execution > > class IpkgOutOfDateException(Exception): > # Raised when the ipkg on the system is out of date > > class UnknownPlanTypeException(Exception): > # Raised when plan is not recognized or known > > class ImageUpdateOnLiveImageException(Exception): > # Raised when BE creation failed or was not performed and actions would > happen on the live image > > class CanceledException(Exception): > # Raised when a cancel has been requested and the API has reached a > point where it can accept the cancel request > > class PlanMissingException(Exception): > # Raised during execution or preparation if no plan exists. > > class UnrecognizedAuthorityException(Exception): > # Raised when refresh is called with an authority the image doesn't > recognize > > class NoImageException(Exception): > # Raised when no image could be found at the specified path. > # Provides the path given > > class NetworkUnavailable(Exception): > # Raised when the network is unavailable and needed > _______________________________________________ > pkg-discuss mailing list > [email protected] > http://mail.opensolaris.org/mailman/listinfo/pkg-discuss > _______________________________________________ pkg-discuss mailing list [email protected] http://mail.opensolaris.org/mailman/listinfo/pkg-discuss
