====================================================== JavaOperaLinkClient - Java Opera Link Client library

Introduction

This is the Opera Link Public API client library for Java. It provides utilities to get and manipulate Opera Bookmarks, Notes and Speed Dials. The application which uses it should provide the library with an application key and secret key received from https://auth.opera.com/service/oauth. The library takes care of authorizing the user and giving easy access to get and modify his Opera Link data.

Copyright and license

The source code included in this distribution is released under the BSD license:

Copyright © 2010, Opera Software All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Opera Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Building

This project can easily be built using Maven. mvn install

Will generate the opera-link-client.jar file in the target folder. And install it into the local maven repository.

Usage description

LinkClient is a class which handles connection with Opera Link server. It supports user authorization and methods for getting and manipulating Opera Link elements.

Before some data with bookmarks, notes or speeddials can be exchanged with server, the application must be granted access. To do so OAuth 1.0a protocol based authorization method is performed. The application must be registered at https://auth.opera.com/service/oauth/applications/ and have its consumerKey and consumerSecret. Register your app as a Web Application, this way you will be able to specify a callback URL.

1. Authorization

To authorize a new user LinkClient object must be created. It obtains a request token and generates the authorization website address where the user must be redirected. This example is taken from the AndroidNotes application (https://github.com/operasoftware/AndroidNotes):

// create new connection
link = new LinkClient(consumerKey, consumerSecret);

// set the callback url, in this case the application has added a following data
// specification to an intent filter in AndroidManifest.xml:
//     <data android:scheme="notes" android:host="operalink.notes.com" />
String callbackUrl = "notes://operalink.notes.com";
try {
    String authorizeUrl = link.getAuthorizationURL(callbackUrl);

    // create intent which will redirect the user to a browser
    Intent i = new Intent(Intent.ACTION_VIEW);
    i.setData(Uri.parse(authorizeUrl));

    // redirect user to the authorization website:
    startActivityForResult(i, REDIRECTION_ACTIVITY);
} catch (LibOperaLinkException e) {
    e.printStackTrace();
}

After the user has granted access to the application and it has been resumed, authorization process can be finalized. The verification code is read from the intent data which was passed in the url query and then is used to obtain an access token.

Uri uri = this.getIntent().getData();
if (uri == null) {
    return;
}

String verifier = uri.getQueryParameter(LinkClient.OAUTH_VERIFIER);
try {

    // obtain access tokens
    link.grantAccess(verifier);

    // save access token and secret for this user
    accessToken = link.getAccessToken();
    tokenSecret = link.getTokenSecret();
} catch (LibOperaLinkException e) {
    e.printStackTrace();
}

When OAuth access token was once generated this line of code is equivalent: LinkClient link = LinkClient.createFromAccessToken(consumerKey, consumerSecret, accessToken, tokenSecret);

2. Accessing and manipulating data

Use LinkClient object to get Opera Link data and to submit some changes to it.

a) Bookmarks: This example shows how to access data, create a new folder and bookmark, how to move them around and finally how to delete them.

// create and append a new sample folder to a root folder bookmarks list
BookmarkFolder sample_folder = new BookmarkFolder('New folder');
link.add(sample_folder);

// create and add a new bookmark to the sample folder
Bookmark bookmark = new Bookmark("Opera Link", "http://link.opera.com/");
bookmark.visited = new Date();
link.addToFolder(bookmark, sample_folder);

// now see that the elements were added - get all of the bookmarks from the
// server
ArrayList<BookmarkFolderEntry> allBookmarks = link.getRootBookmarks(false);
// and check if the last element is the sample folder added and it contains the 
// bookmark
int bookmarksSize = allBookmarks.size();
assert(allBookmarks.get(bookmarksSize - 1).isFolder());
assert(allBookmarks.get(bookmarksSize - 1).title.equals('New folder'));
sample_folder = (BookmarkFolder) allBookmarks.get(bookmarksSize - 1);
assert(sample_folder.getChildren().get(0).isBookmark());
bookmark = (Bookmark) sample_folder.getChildren().get(0);
assert(bookmark.title.equals('Opera Link')) ;

// or just get from the server a content of the folder
ArrayList<BookmarkFolderEntry> sampleFolderContent =
    link.getBookmarksFromFolder(sample_folder, false);
assert(sampleFolderContent.get(0).title.equals('Opera Link')) ;


// Now let's reorder the bookmarks:
// create another folder where already created folder and bookmark can be
// moved into
BookmarkFolder folderForMovedElements = new BookmarkFolder('Folder with moved elements');
link.add(folderForMovedElements);

// move one folder into another
link.moveInsideFolder(sample_folder, folderForMovedElements)

// move the bookmark outside of sample folder and place it in a root folder
// at the last position
link.moveToRootFolder(bookmark);
// or place it in a root folder before the added folder for moved elements
link.moveBeforeElement(bookmark, folderForMovedElements);


// Time to clean up:
// trash added elements
link.trash(bookmark);
link.trash(sample_folder);
link.trash(folderForMovedElements);
// or delete them
link.delete(bookmark);
link.delete(sample_folder);
link.delete(folderForMovedElements);

b) Notes: Retrieving and manipulating notes data is analogical to bookmarks

c) Speed dials: This example shows how to access, create, update and remove speed dials. In contrast to notes and bookmarks speed dials can not be moved.

// create a new speeddial and add it at first position
SpeedDial dial = new SpeedDial("http://opera.com/", "Opera Main Page", 1);
link.add(dial);

// send updates to a dial
dial.title = "Opera";
link.update(dial);

// access all of your speed dials
ArrayList<SpeedDial> dials = link.getSpeedDials();

// delete the new added one:
link.delete(dial);

3. Folder properties

BookmarkFolder and NoteFolder have some special properties you can access. Those are related to their special use on the devices, for example Opera Mini users can only access a folder for which isTargetMini method returns true. For more details see documentation.