forked from estebanm/JavaOperaLinkClient
-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.txt
224 lines (172 loc) · 8.34 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
======================================================
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.