From 91b1efc97e904a2323559002580eb7d6d8576acb Mon Sep 17 00:00:00 2001 From: Christian Schabesberger Date: Sat, 10 Nov 2018 10:50:13 +0100 Subject: [PATCH] add documentation of StreamingService --- README.md | 2 +- .../schabi/newpipe/extractor/ServiceList.java | 22 ++++ .../newpipe/extractor/StreamingService.java | 116 +++++++++++++++++- 3 files changed, 137 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 69d897e6a..b13f04ff0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # NewPipe Extractor -[![Build Status](https://travis-ci.org/TeamNewPipe/NewPipeExtractor.svg?branch=master)](https://travis-ci.org/TeamNewPipe/NewPipeExtractor) [![JIT Pack Badge](https://jitpack.io/v/TeamNewPipe/NewPipeExtractor.svg)](https://jitpack.io/#TeamNewPipe/NewPipeExtractor) [Documentation](https://teamnewpipe.github.io/NewPipeExtractor/javadoc/) +[![Build Status](https://travis-ci.org/TeamNewPipe/NewPipeExtractor.svg?branch=master)](https://travis-ci.org/TeamNewPipe/NewPipeExtractor) [![JIT Pack Badge](https://jitpack.io/v/TeamNewPipe/NewPipeExtractor.svg)](https://jitpack.io/#TeamNewPipe/NewPipeExtractor) [Documentation](https://teamnewpipe.github.io/documentation/) NewPipe Extractor is a library for extracting things from streaming sites. It is a core component of [NewPipe](https://github.com/TeamNewPipe/NewPipe), but could be used independently. diff --git a/extractor/src/main/java/org/schabi/newpipe/extractor/ServiceList.java b/extractor/src/main/java/org/schabi/newpipe/extractor/ServiceList.java index 846355ede..36690438f 100644 --- a/extractor/src/main/java/org/schabi/newpipe/extractor/ServiceList.java +++ b/extractor/src/main/java/org/schabi/newpipe/extractor/ServiceList.java @@ -8,6 +8,24 @@ import java.util.List; import static java.util.Arrays.asList; import static java.util.Collections.unmodifiableList; +/* + * Copyright (C) Christian Schabesberger 2018 + * ServiceList.java is part of NewPipe. + * + * NewPipe is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * NewPipe is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with NewPipe. If not, see . + */ + /** * A list of supported services. */ @@ -19,6 +37,10 @@ public final class ServiceList { public static final YoutubeService YouTube; public static final SoundcloudService SoundCloud; + /** + * When creating a new service, put this service in the end of this list, + * and give it the next free id. + */ private static final List SERVICES = unmodifiableList( asList( YouTube = new YoutubeService(0), diff --git a/extractor/src/main/java/org/schabi/newpipe/extractor/StreamingService.java b/extractor/src/main/java/org/schabi/newpipe/extractor/StreamingService.java index a85d8f3a1..b798ec92c 100644 --- a/extractor/src/main/java/org/schabi/newpipe/extractor/StreamingService.java +++ b/extractor/src/main/java/org/schabi/newpipe/extractor/StreamingService.java @@ -14,11 +14,38 @@ import org.schabi.newpipe.extractor.utils.Localization; import java.util.Collections; import java.util.List; +/* + * Copyright (C) Christian Schabesberger 2018 + * StreamingService.java is part of NewPipe. + * + * NewPipe is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * NewPipe is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with NewPipe. If not, see . + */ + public abstract class StreamingService { + + /** + * This class holds meta information about the service implementation. + */ public static class ServiceInfo { private final String name; private final List mediaCapabilities; + /** + * Creates a new instance of a ServiceInfo + * @param name the name of the service + * @param mediaCapabilities the type of media this service can handle + */ public ServiceInfo(String name, List mediaCapabilities) { this.name = name; this.mediaCapabilities = Collections.unmodifiableList(mediaCapabilities); @@ -37,6 +64,10 @@ public abstract class StreamingService { } } + /** + * LinkType will be used to determine which type of URL you are handling, and therefore which part + * of NewPipe should handle a certain URL. + */ public enum LinkType { NONE, STREAM, @@ -47,6 +78,16 @@ public abstract class StreamingService { private final int serviceId; private final ServiceInfo serviceInfo; + /** + * Creates a new Streaming service. + * If you Implement one do not set id within your implementation of this extractor, instead + * set the id when you put the extractor into + * ServiceList. + * All other parameters can be set directly from the overriding constructor. + * @param id the number of the service to identify him within the NewPipe frontend + * @param name the name of the service + * @param capabilities the type of media this service can handle + */ public StreamingService(int id, String name, List capabilities) { this.serviceId = id; this.serviceInfo = new ServiceInfo(name, capabilities); @@ -68,24 +109,93 @@ public abstract class StreamingService { //////////////////////////////////////////// // Url Id handler //////////////////////////////////////////// + + /** + * Must return a new instance of an implementation of LinkHandlerFactory for streams. + * @return an instance of a LinkHandlerFactory for streams + */ public abstract LinkHandlerFactory getStreamLHFactory(); + + /** + * Must return a new instance of an implementation of ListLinkHandlerFactory for channels. + * If support for channels is not given null must be returned. + * @return an instance of a ListLinkHandlerFactory for channels or null + */ public abstract ListLinkHandlerFactory getChannelLHFactory(); + + /** + * Must return a new instance of an implementation of ListLinkHandlerFactory for playlists. + * If support for playlists is not given null must be returned. + * @return an instance of a ListLinkHandlerFactory for playlists or null + */ public abstract ListLinkHandlerFactory getPlaylistLHFactory(); + + /** + * Must return an instance of an implementation of SearchQueryHandlerFactory. + * @return an instance of a SearchQueryHandlerFactory + */ public abstract SearchQueryHandlerFactory getSearchQHFactory(); //////////////////////////////////////////// // Extractor //////////////////////////////////////////// + + /** + * Must create a new instance of a SearchExtractor implementation. + * @param queryHandler specifies the keyword lock for, and the filters which should be applied. + * @param localization specifies the language/country for the extractor. + * @return a new SearchExtractor instance + */ public abstract SearchExtractor getSearchExtractor(SearchQueryHandler queryHandler, Localization localization); + + /** + * Must create a new instance of a SuggestionExtractor implementation. + * @param localization specifies the language/country for the extractor. + * @return a new SuggestionExtractor instance + */ public abstract SuggestionExtractor getSuggestionExtractor(Localization localization); + + /** + * Outdated or obsolete. null can be returned. + * @return just null + */ public abstract SubscriptionExtractor getSubscriptionExtractor(); + + /** + * Must create a new instance of a KioskList implementation. + * @return a new KioskList instance + * @throws ExtractionException + */ public abstract KioskList getKioskList() throws ExtractionException; + /** + * Must create a new instance of a ChannelExtractor implementation. + * @param linkHandler is pointing to the channel which should be handled by this new instance. + * @param localization specifies the language used for the request. + * @return a new ChannelExtractor + * @throws ExtractionException + */ public abstract ChannelExtractor getChannelExtractor(ListLinkHandler linkHandler, Localization localization) throws ExtractionException; + + /** + * Must crete a new instance of a PlaylistExtractor implementation. + * @param linkHandler is pointing to the playlist which should be handled by this new instance. + * @param localization specifies the language used for the request. + * @return a new PlaylistExtractor + * @throws ExtractionException + */ public abstract PlaylistExtractor getPlaylistExtractor(ListLinkHandler linkHandler, Localization localization) throws ExtractionException; + + /** + * Must create a new instance of a StreamExtractor implementation. + * @param linkHandler is pointing to the stream which should be handled by this new instance. + * @param localization specifies the language used for the request. + * @return a new StreamExtractor + * @throws ExtractionException + */ public abstract StreamExtractor getStreamExtractor(LinkHandler linkHandler, Localization localization) throws ExtractionException; //////////////////////////////////////////// @@ -165,9 +275,11 @@ public abstract class StreamingService { return getStreamExtractor(getStreamLHFactory().fromUrl(url), NewPipe.getPreferredLocalization()); } - /** - * figure out where the link is pointing to (a channel, video, playlist, etc.) + * Figures out where the link is pointing to (a channel, a video, a playlist, etc.) + * @param url the url on which it should be decided of which link type it is + * @return the link type of url + * @throws ParsingException */ public final LinkType getLinkTypeByUrl(String url) throws ParsingException { LinkHandlerFactory sH = getStreamLHFactory();