|
|
| Line 1: |
Line 1: |
| − | The Eclipse User Storage Service (USS) allows Eclipse projects to store user-specific project information on the Eclipse Foundation servers. The goal is to make it easy for our projects to offer a better user experience by storing relevant information in a central location.
| |
| | | | |
| − | The git project is moved to http://git.eclipse.org/c/usssdk/org.eclipse.usssdk.git/
| |
| − |
| |
| − | '''IMPORTANT: the USS is intended to be used for data that may be exposed publicly. Application developers must not use this service to store personal data, such as name, email address, host/server information or anything else that is best suited for local storage or the Eclipse Secure Storage.'''
| |
| − |
| |
| − | The USS has two components:
| |
| − | * REST API server. The actual storage service.
| |
| − |
| |
| − | * USS SDK: a java API to interface with the REST server from an Eclipse workspace. The SDK handles login/authentication, session management and storage/retrieval of data.
| |
| − |
| |
| − | == Getting Started ==
| |
| − |
| |
| − | To store data in the USS, an Eclipse project must first apply for an '''Application Token''' by sending a request to the Eclipse Webmaster. The Application Token is a string that allows projects to differentiate their user data from that of other projects. Since the Application Token is used in the context of Open Source projects, it is not private, it is not hidden, and may even be used in source code. It is not meant to be an authorization or authentication mechanism; however, there are plans to increase the security of this mechanism, as any Eclipse project could use any authorized token. An Application Token may be shared with other Eclipse projects.
| |
| − |
| |
| − | The USS uses [https://aaronparecki.com/oauth-2-simplified/ OAuth] to allow the user to grant fine-grained authorization for a specific Eclipse project to access their user data. Each Eclipse project is considered as a separate ''OAuth Client''. Each Eclipse project must apply to the Eclipse Webmaster for a unique ''ID'' and ''secret''. The OAuth specification describes a work flow to to prompt the user to authorize an OAuth Client (the Eclipse project) to access the user's data. If the user approves, the OAuth Client is provided an ''access code''. This access code must be provided on each call when accessing the USS.
| |
| − |
| |
| − | == Using the USS SDK ==
| |
| − |
| |
| − | The USS SDK is a library that simplifies accessing the USS.
| |
| − |
| |
| − | === Configuring the USS SDK ===
| |
| − |
| |
| − | There are two steps for configuring the USS SDK:
| |
| − |
| |
| − | # Provide the client ID to application name mapping
| |
| − | # Configure the USS OAuth Credentials Provider
| |
| − |
| |
| − | ==== Configuring the Client ID to Application Name Mapping ====
| |
| − |
| |
| − | The USS SDK provides a *Linked Accounts* preference page that lists current credentials with the client (application) and user account. To have your application name listed, add an extension to the <code>org.eclipse.userstorage.oauth.clients</code> extension point to describe the MPC app:
| |
| − | <source lang="xml">
| |
| − | <extension
| |
| − | point="org.eclipse.userstorage.oauth.clients">
| |
| − | <client
| |
| − | id="eclipse_uss_sdk"
| |
| − | name="USS SDK Examples"
| |
| − | icon="icons/eclipse.png"
| |
| − | authURI="https://accounts.eclipse.org/">
| |
| − | </client>
| |
| − | </extension>
| |
| − | </source>
| |
| − |
| |
| − | ==== Configuring the OAuth Credentials Provider ====
| |
| − |
| |
| − | The USS SDK's <code>EclipseOAuthCredentialsProvider</code> class is used to obtain authorization from the user for your application to work with their user data managed by the Eclipse Foundation.
| |
| − |
| |
| − | It's easiest to use the <code>OAuthParameters</code> class to configure your OAuth parameters. See the class comment for details on configuring your own instance.
| |
| − |
| |
| − | <source lang="java">
| |
| − | final IStorage storage = StorageFactory.DEFAULT.create(appToken);
| |
| − | OAuthParameters oauthParameters = new MyOAuthParameters();
| |
| − | EclipseOAuthCredentialsProvider credentialsProvider = new EclipseOAuthCredentialsProvider(oauthParameters);
| |
| − | credentialsProvider.setShell(getViewSite());
| |
| − | storage.setCredentialsProvider(credentialsProvider);
| |
| − |
| |
| − | // and now start fetching content
| |
| − | IBlob b = storage.getBlob("xxx");
| |
| − | </source>
| |
| − |
| |
| − | See the <code>org.eclipse.userstorage.sdk</code>'s [http://git.eclipse.org/c/usssdk/org.eclipse.usssdk.git/tree/org.eclipse.userstorage.tests/src/org/eclipse/userstorage/tests/StorageTests.java?h=master <code>USSBrowsingView</code>] for a running example of configuring and fetching content from the USS.
| |
| − |
| |
| − | === Storing and Fetching Data using the USS SDK ===
| |
| − |
| |
| − | The USS SDK Storage Tests class provides a good sample implementation. Please see: http://git.eclipse.org/c/oomph/uss.git/tree/org.eclipse.userstorage.tests/src/org/eclipse/userstorage/tests/StorageTests.java
| |
| − |
| |
| − | === Additional UI Extension Points for the USS SDK ===
| |
| − |
| |
| − | The USS provides a tool item and menu (Help > Eclipse User Storage) that opens an extensible cascaded menu with ID <tt>org.eclipse.userstorage.accounts</tt>. This menu has the following format:
| |
| − | <pre>
| |
| − | <Account widget> menuId: org.eclipse.userstorage.accounts
| |
| − | +- Open My Account opens accounts.eclipse.org
| |
| − | +----------------- separator tagged `actions`
| |
| − | +----------------- separator tagged `accounts`
| |
| − | +- Authorized Applications opens USS OAuth pref page
| |
| − | +- USS Example Browser list of authorized applications
| |
| − | +- Sign Out discards all data
| |
| − | +----------------- separator tagged `additions`
| |
| − | </pre>
| |
| − | For example, the Marketplace Client adds an item to open the MPC on the user's favourites:
| |
| − | <source lang="xml">
| |
| − | <extension
| |
| − | point="org.eclipse.ui.menus">
| |
| − | <menuContribution
| |
| − | allPopups="false"
| |
| − | locationURI="menu:org.eclipse.userstorage.accounts?after=actions">
| |
| − | <command
| |
| − | commandId="org.eclipse.epp.mpc.ui.command.showFavorites"
| |
| − | icon="icons/marketplace16.png"
| |
| − | label="%command.account.favorites.label"
| |
| − | style="push"
| |
| − | tooltip="%command.account.favorites.tooltip">
| |
| − | </command>
| |
| − | </menuContribution>
| |
| − | </extension>
| |
| − | </source>
| |
| − |
| |
| − | == Projects Using USS ==
| |
| − | * Oomph: allowing users to save their preferences to the USS for persistence across workspaces on different computers and/or virtual boxes.
| |
| − | * Marketplace Client (MPC): (planned) to store user favorites to the USS.
| |
