Spaces/Use Cases

From Eclipsepedia

Jump to: navigation, search

Contents

Use Case One: Initial Publish

  1. File > New > Project > Plug-in Development > Plug-in Project > "demo" ... Hello World ...
  2. Right-click menu over project "demo" and choose Spaces > Publish...
  3. A wizard/dialog box opens to ask me a few questions including:
    1. Which spaces adapter to use. I will choose "AOL Eclipse Spaces" for this example.
    2. Because this is the first time I have used AOL Eclipse Spaces in this instance of Eclipse, I am asked for my login and password. These are stored in the Eclipse workspace so that I don't have to enter them in the future.
  4. The Spaces plug-in does a client side build and then uploads the results to the storage server:
    1. Compile all the java code (usually already compiled via incremental compiler)
    2. Jar-up the class files.
    3. Jar into a plug-in jar with correct manifest file, etc.
    4. Create a feature.xml for this one plug-in. Saves the feature.xml along with the plugin.xml so that it can be re-used. (The Spaces plug-in either asks for the necessary information via the wizard, or it assumes some defaults, or it generates some defaults from the plug-in code.)
    5. Jar into a feature jar with correct manifest file, etc.
    6. Download the site.xml from my AOL Eclipse Spaces update site. If there is no site.xml, generate a new empty site.xml locally.
    7. Add this new feature to the local site.xml
    8. Upload the new site.xml, feature jar, and plugin jar to my AOL Eclipse Spaces update site.
  5. When the publish action is complete, the wizard shows me the public url to my update site.
    1. My friends and I can go to my AOL Eclipse Spaces update site using the Eclipse Update Manager (based on my AOL XDrive permissions) and download and install my "demo" plug-in.

implementation

  • Step 3 starts with Spaces.getSpaceProviderItems() and shows the ISpaceProviderHandle.getName() and .getDescription() to the user so that he/she can choose one. ??
  • Once he/she chooses one, it uses ISpaceProviderHandle.getSpaceProvider() to get the provider object.
  • Then what??
Henrik - regarding step 3:
  • Actually, step 3 should start with "select space" from the Space Catalog, but since this use case describes initial use, the catalog is empty, they do not have "a space" anywhere - so user should select a provider first.
  • Service provider specific wizards can be added as extensions to the plugin "com.eclipse.spaces.ui" - it has an "addSpaceWizard" point, but this is placeholder right now.
    • The addspace wizard extension point is used to add a wizard for a "providerScheme" - the "providerScheme" for AOL would be what they choose to use for their URIs (probably "xdrive").
  • The generic spaces.ui should use "ISpaceProviderHandle.getProviderScheme()" to get the key to locate the wizard to use for adding a space.
  • If no wizard was registered for the scheme - then a generic wizard should be displayed. This wizard asks for the URI of the space to add - (similar to how you add a CVS or SVN repository). The user does not have to enter the ":spaces:providerScheme" part or the URI, as that is already known from the selected provider. It can however not help with any additional fields in the URI, nor signup - that is the reason why a provider may want to add their own wizard, as that wizard can either handle sign-up from within the wizard, or refer the user to a web page where they should sign up, as well as handling provider specific parts of the URI.
  • Spaces handles BasicAuthorization information (See Spaces/Authorization Support), so the generic "add space" can ask for login/password and either store it in memory for the current session, or in the keyring (Done via simple calls to "SpaceAuthroization"). The authorization mechanism can easiliy be extended later, to allow for other Authorization schemes.
    • We should provide a generic UI plugin for getting the credentials for Basic Credentials - this plugin is in effect when running

with a UI. (It is invoked when credentials are not known).

    • An implementor of a new authorization scheme must add an extension point to their headless space provider plugin - if there is an extension it is used to obtain needed password, if it is not extended, the provider would either get the password from the keyring or throw an exception.
    • Optionally implement the addspace wizard if provider wants the user to be able to enter the password when adding the space. Alternatively, we expand the generic wizard to also asks for login/password and store that in the eclipse key ring for the URI.
  • Similar to the CVS/SVN, the connection to the space can be tested before adding the space to the SpaceCatalog.
  • The space is added to the space catalog using "SpaceCatalog.addSpaceAddress(URI address)"
Henrik - regarding step 4&5:

As it is possible to publish different things in different ways, this is what the user does:

  • One of:
    • Start the "Space Publishing Wizard" - the first question is "what do you want to publish" - user presses Browse and browses for the resource to publish.
    • Select the Resource in the navigator and do a right mouse click - in the context menu there is an action "Publish in a Space". This leads to the same "Space Publishing Wizard", but it can then skip the first page as the resource is already selected.
  • Select the space to publish to
    • Done by getting available spaces from "SpaceCatalog.getSpaceAddresses()" - right now there is no better "name" associated with a catalog entry - this should be added to space catalog.
  • Select how to publish the selected resource - a list of possible ways is presented to the user, the user selects one.
    • Done by:
      • Getting the ISpace for the address "Spaces.getSpace(address)"
      • Calling Spaces.getApplicablePublishingOperations(IResource theSelectedResource, ISpace theSelectedSpace)
      • Get a list of IPublishingOperation back - this list is displayed
      • The user picks one operation (selectedPublishingOperation)
  • Start a wizard to handle details for the publishing operation
    • The org.eclipse.spaces.ui plugin has an extension point for publishing operation wizards (undefined how to get it, but suggest from "SpacesUI.getPublishingOperationWizard(selectedPublishingOperation)"
  • The wizard takes user through the specific steps for the publisher - options etc.
    • The wizard steps change properties in the "selectedPublishingOperation" until done
    • To execute job call "selectedPublishingOperation.getJob()" and schedule it as any other Eclipse Job
      • (The implementation handles locking so publishing jobs do not step on each other)
      • The job will do whatever it needs - make sure things are compiled, copy results into the EFS provided by a space provider etc.)
  • A publisher that has "URLs to share" - for instance for an "update site" will present this on its last page. (It is possible to do more with this later - perhaps looking up the URL's even after publishing is done in case user forgot - for update sites, the formula of getting to the update site from a root URL to the space is given, but for other types of publishing it may not be that easy. Not needed now, but there is information in the space metadata (inside the space) that can be displayed).
  • publishing is done
Thomas - regarding step 4:

While it's true that the incremental compiler usually keeps all class files up-to-date, the task of creating the jar file is a bit more complex. Some questions need to be answered:

  1. Where is the output folder?
  2. Are there many output folders?
  3. Was the compilation successful?
  4. What more besides the compiled classes and manifest should go into the plug-in jar?

I see two ways of building a plug-in jar file:

  1. Use the PDE Export deployable plug-ins and fragments function (requires user interaction)
  2. Use Buckminster and call on actions that always exists for any given plug-in from within Java. No user interaction needed.


The feature creation can be fairly straight forward but there is one thing that we must address.

A feature can list plug-ins, included features, and requirements. The last one is important since it tells the Update Manager that in order to install this feature in the designated target, these requirements must be fulfilled. If we fail to provide this information, then any plug-in authored on a target platform configured different from the one used by the consumer will break the consumers configuration. The Update Manager will silently install the feature but it will not run. Instead it will produce cryptic messages in the error log.

Another factor to consider is if the plug-in should be "unpacked" or not. Some plug-ins require that they are unpacked in order to function. This attribute must be set in the feature.xml that references the plug-in.

The implementation that I'm currently working on supports the given use-cases. In essence, there is a IOSGiRepository to which you can publish IBundle instances (plug-ins). It has the concept of IBundleGroup (roughly similar to a feature) and IGroupCategory (similar to a category on the update site). It allows for all types of editing and all actions performed on it are in-memory actions. Once all editing has been made, the repository can be written out to a PublishingArea in some form suitable for consumption. The first form implemented is of course the Update Site. Other planned forms are OBR and p2.

The repository can also load itself from a PublishingArea.

In it's simplest form, the repository can work with plug-ins only. Free-standing plug-ins will end up in uncategorized features of their own with the same name as the plug-in. It will not be possible to add other plug-ins to such a feature since the abstraction will hide it completely.

Use Case Two: Incremental Publish

  1. I modify the "demo" plug-in project to do something more interesting.
  2. Right-click menu on the "demo" project to do Spaces > Publish...
    1. Because I've already published it to my AOL Eclipse Spaces and because I've already logged-in in this Eclipse instance, it just compiles, builds, and uploads the result.
    2. Because I did not change the version number in the plug-in, this new copy of the "demo" feature overwrites the existing feature on the update site.
  3. When the publish action is complete, the wizard shows me the public url to my update site. It is the same public url as it was for use case one.
Thomas:

This will work as expected using the IOSGiRepository

Use Case Three: Publish New Version

  1. I modify the "demo" plug-in project yet again, this time to fix a bug.
    1. I update the version number in the plugin.xml from 0.1 to 0.2
  2. Right-click menu on the "demo" project to do Spaces > Publish...
    1. Because I've already published it to my AOL Eclipse Spaces and because I've already logged in in this Eclipse instances, it just compiles, builds, and uploads the result.
    2. Because I changed the version number in the plug-in, this new copy of the "demo" feature will be added to site.xml and now there will be two versions of the demo feature on my AOL Eclipse Spaces.
  3. When the publish action is complete, the wizard shows me the public url to my update site. It is the same public url as it was for use case one.
Henrik - these are requirements on the OSGi Publishing Operation Thomas is working on
Thomas:

This will work as expected using the IOSGiRepository

Use Case Four: Publish a Second Plug-in

  1. I use File > New > Project > Plug-in Project ... to make a new "coolness" plug-in.
  2. Right-click menu on the "coolness" project to do Spaces > Publish...
  3. A wizard/dialog box opens to ask me a few questions including:
    1. Which spaces adapter to use. I will choose "AOL Eclipse Spaces" for this example.
    2. Because I've already logged-in to AOL Eclipse Spaces in this Eclipse instance, it just compiles, builds, and uploads the result.
    3. Because this is a new plug-in/feature, this new "coolness" feature will added to site.xml and now there will be two versions of the "demo" feature (use cases 1 and 2) and one of the "coolness" feature on my AOL Eclipse Spaces.
  4. When the publish action is complete, the wizard shows me the public url to my update site. It is the same public url as it was for use case one.
Henrik

Flow is slightly different as shown in the initial publish use case.

  • A question is asked which space to use, not which space provider
  • Rest as described.

Use Case Five: Withdraw

  1. I decide to withdraw the "coolness" plug-in at my AOL Eclipse Spaces.
  2. Right-click menu on the "coolness" project to do Spaces > Disconnect...
  3. A dialog asks me if I am sure
  4. Then it removes all instances of the "coolness" project from my AOL Eclipse Spaces update site.
    1. If I had done a Spaces > Share... or Spaces > Promote... or any of the other Spaces actions, the Spaces > Disconnect... would also clean up those actions.
    2. Additionally, if I go to do a Spaces > Publish... on the "coolness" project in the future, I will be prompted again for which spaces provider to publish to.
Henrik

This raises several issues to discuss:

  • The use cases suggest stickiness between the published resource, publishing operation, and space. I.e. that there is a record of "what was published where"
  • Since one resource can be published in different forms in different places, the operation needs to list all such places to be able to withdraw only one of them (or All)
  • As an alternative - a withdraw wizard could do the "reverse" of the publishing operation wizard - user selects resource, and space, and gets applicable "withdraws"
  • In any case, the withdraw should be handled by the PublishingOperation instance that published the stuff since it knows the format. This is not specified in the API.
Henrik (after discussion with Thomas)

Withdraw operation should be performed either via publishing operations that keep a publishing area i sync, or via a view into a publishing area. Consider the scenario with a very simple "publish a file into 'files'". A file is published. Much later, user does not want this file to be published, but has lost the actual file. It must be possible to view what has been published in each area (each type of area may require its own view.

A PublishingArea view can be generic if it makes sense to show the content as just a file structure, but in some cases it may be better to make this opaque, and instead view/edit using a wizard. This is not covered by the current implementation. The OSGi publishing that Thomas is working on has such capabilities.

Expect to build support for this when needed.

Use Case Six: Repair

  1. I use the normal AOL Xdrive interface to manipulate the files on my Xdrive. I delete the older versions of the "demo" plug-in.
    1. This messes up the update site, of course, but I can fix it by publishing again:
  2. Right-click menu on the "demo" project to do Spaces > Publish...
    1. Because I've already published it to my AOL Eclipse Spaces and because I've already logged-in in this Eclipse instance, it just compiles, builds, and uploads the result.
    2. Because I did not change the version number in the plug-in, this new copy of the "demo" feature overwrites the existing feature on the update site.
    3. Also the update site is rebuilt and the older versions of the "demo" feature are removed from the site.xml file.
  3. When the publish action is complete, the wizard shows me the public url to my update site. It is the same public url as it was for use case one.
Henrik

I assume this "repair write" just fixes things that are missing, and overwrites things that are corrupt. Otherwise it needs to track down all published things and refresh... and everything may not be in the user's workspace...

Use Case Seven: Initial Share of Published Project

  1. I decide to share the source code to the "demo" plug-in at my AOL Eclipse Spaces.
  2. Right-click menu on the "demo" project to do Spaces > Share...
  3. Sets up a CVS or SVN (depends on the spaces provider) connection to my AOL Eclipse Spaces.
    1. Sets the CVS/SVN module name to "demo".
  4. Switches me to the Team Synchronize perspective where I can complete the source code commit.

Use Case Eight: Describe URLs

  1. I want to share my source code with a colleague, but I don't remember how to connect to the repository.
  2. Right-click menu on the "demo" project to do Spaces > URLs...
  3. Opens a dialog box that displays the public urls/uris to all of the spaces bits about this project. The url to the update site that I have Spaces > Publish...ed; the url to the CVS/SVN repository that I have Spaces > Share...ed; etc.
Henrik

I mentioned this earlier, had not noticed that it was a separate use case. To do this:

  • Find all spaces in the workspace - "SpacesCatalog.getSpaceAddresses()"
  • Get an ISpace for each address "Spaces.getSpace(address)"
  • Ask the ISpace for it's publishing areas "PublishingArea.getAreasInSpace(space)"
    • for each area ask for:
    • area name and type (update site, list of files, etc.)
    • "area.getAreaConsumptionURL()" - this is the URL to present to the user for the published stuff
  • Ask the ISpace for the URI to the source repository using "ISpace.getSourceRepository()" - check that the space supports a source repository first using "ISpace.getCapabilities().contains(SpaceCapability.SOURCE_REPOSITORY)".

Use Case Nine: Initial Share of New Project

  1. I use File > New > Project > Plug-in Project ... to make a new "nifty" plug-in.
  2. Right-click menu on the "nifty" project to do Spaces > Share...
  3. A wizard/dialog box opens to ask me a few questions including:
    1. Which spaces adapter to use. I will choose "AOL Eclipse Spaces" for this example.
    2. Because I've already logged-in to AOL Eclipse Spaces in this Eclipse instance, it proceeds to:
  4. Sets up a CVS or SVN (depends on the spaces provider) connection to my AOL Eclipse Spaces.
    1. Sets the CVS/SVN module name to "nifty".
  5. Switches me to the Team Synchronize perspective where I can complete the source code commit.
Henrik

To do this:

  • Get the URI to a space's source repo by
    • Ask user to select a space from list of spaces in the SpaceCatalog
    • Get the ISpace instances for the addresses
    • Prune the list to only include the spaces that provide a source repository ("space.getCapabilities().contains(....SOURCE...)").
    • User selects a space
    • get the source repository URL from the space ISpace.getSourceRepository()
  • Parse the URI to direct to the correct wizard in the correct team plugin
    • Hopefully everything needed can be figured out from this URI, but if it can't then the ISpace needs to return something different.

There is also a case missing:

  • Something has already been shared - so the Source Repo is already known in the Workspace, but instead of syncronizing, there is the need to do team > share first. (i.e. same case, but with repository connection already set up)

Use Case Ten: Subsequent Share

  1. I modify the "nifty" project with some nifty new features.
  2. Right-click menu on the "nifty" project do do Spaces > Share...
  3. Because I've already set up the share of this project to my AOL Eclipse Spaces repository, it takes me directory to:
  4. Switches me to the Team Synchronize perspective where I can complete the source code commit.