1 /*
2 * Licensed to The Apereo Foundation under one or more contributor license
3 * agreements. See the NOTICE file distributed with this work for additional
4 * information regarding copyright ownership.
5 *
6 *
7 * The Apereo Foundation licenses this file to you under the Educational
8 * Community License, Version 2.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of the License
10 * at:
11 *
12 * http://opensource.org/licenses/ecl2.txt
13 *
14 * Unless required by applicable law or agreed to in writing, software
15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
17 * License for the specific language governing permissions and limitations under
18 * the License.
19 *
20 */
21
22 package org.opencastproject.publication.youtube;
23
24 import org.opencastproject.publication.youtube.auth.ClientCredentials;
25
26 import com.google.api.services.youtube.model.Playlist;
27 import com.google.api.services.youtube.model.PlaylistItem;
28 import com.google.api.services.youtube.model.PlaylistItemListResponse;
29 import com.google.api.services.youtube.model.PlaylistListResponse;
30 import com.google.api.services.youtube.model.SearchListResponse;
31 import com.google.api.services.youtube.model.Video;
32
33 import java.io.IOException;
34
35 /**
36 * Provides convenient access to {@link com.google.api.services.youtube.YouTube} service.
37 */
38 public interface YouTubeAPIVersion3Service {
39
40 /**
41 * Configure the underlying {@link com.google.api.services.youtube.YouTube} instance.
42 * @param credentials may not be {@code null}
43 * @throws IOException when configuration files not found.
44 */
45 void initialize(ClientCredentials credentials) throws IOException;
46
47 /**
48 * Search for videos on predefined channel.
49 * @param queryTerm may not be {@code null}
50 * @param pageToken may not be {@code null}
51 * @param maxResults may not be {@code null}
52 * @return zero or more results. Will not be {@code null}.
53 * @throws IOException when search fails.
54 */
55 SearchListResponse searchMyVideos(String queryTerm, String pageToken, long maxResults) throws IOException;
56
57 /**
58 * Get video by id.
59 * @param videoId may not be {@code null}
60 * @return null when not found.
61 * @throws IOException
62 */
63 Video getVideoById(String videoId) throws IOException;
64
65 /**
66 * Get playlist by title.
67 * @param title may not be {@code null}
68 * @return null when not found.
69 * @throws IOException when lookup fails.
70 */
71 Playlist getMyPlaylistByTitle(String title) throws IOException;
72
73 /**
74 * Page through all YouTube playlists of predefined channel.
75 * @param pageToken identifies a page in result-set.
76 * @param maxResults limit on number of results.
77 * @return zero or more {@link com.google.api.services.youtube.model.Playlist}
78 * @throws IOException when lookup fails.
79 */
80 PlaylistListResponse getMyPlaylists(String pageToken, long maxResults) throws IOException;
81
82 /**
83 * Find YouTube playlist by id.
84 * @param playlistId may not be {@code null}
85 * @param pageToken may not be {@code null}
86 * @param maxResults may not be {@code null}
87 * @return will not be {@code null}
88 * @throws IOException when lookup fails.
89 */
90 PlaylistItemListResponse getPlaylistItems(String playlistId, String pageToken, long maxResults) throws IOException;
91
92 /**
93 * Upload a video to predefined YouTube channel.
94 * @param videoUpload may not be {@code null}
95 * @return YouTube object with non-null id.
96 * @throws IOException when transaction fails.
97 */
98 Video addVideoToMyChannel(VideoUpload videoUpload) throws IOException;
99
100 /**
101 * Add a previously uploaded video to specified YouTube playlist.
102 * @param playlistId may not be {@code null}
103 * @param videoId may not be {@code null}
104 * @return YouTube object which describes mapping, with non-null id.
105 * @throws IOException
106 */
107 PlaylistItem addPlaylistItem(String playlistId, String videoId) throws IOException;
108
109 /**
110 * Creates YouTube Playlist and adds it to the authorized account.
111 * @param title may not be {@code null}
112 * @param description may not be {@code null}
113 * @param tags zero or more tags to be applied to playlist on YouTube.
114 */
115 Playlist createPlaylist(String title, String description, String... tags) throws IOException;
116
117 /**
118 * Remove a previously uploaded video from YouTube.
119 * @param videoId may not be {@code null}
120 * @throws Exception when transaction fails.
121 */
122 void removeMyVideo(String videoId) throws Exception;
123
124 /**
125 * Remove a previously uploaded video from specified YouTube playlist.
126 * @param playlistId may not be {@code null}
127 * @param videoId may not be {@code null}
128 * @throws IOException when transaction fails.
129 */
130 void removeVideoFromPlaylist(String playlistId, String videoId) throws IOException;
131
132 /**
133 * Remove a previously created YouTube playlist.
134 * @param playlistId may not be {@code null}
135 * @throws IOException when transaction fails.
136 */
137 void removeMyPlaylist(String playlistId) throws IOException;
138
139 }