Download API Javadoc

[phocker]

Is there anyplace to download the API Javadoc for SageTV? I like that it is online, but want to import it into my IDE for development.

Paul

[Surtr]

I second that.

Additionally, the API documentation available at http://download.sage.tv/api/ doesn't have the full API. For instance, where can the api documentation be found for the classes sage.Favorite and sage.Channel?

[Opus4]

Originally Posted by Surtr

Additionally, the API documentation available at http://download.sage.tv/api/ doesn't have the full API. For instance, where can the api documentation be found for the classes sage.Favorite and sage.Channel?

ChannelAPI and FavoriteAPI are right there at the link you posted... you don't see them listed?

- Andy

[Surtr]

yep, I see all the sage.api.* classes like sage.api.ChannelAPI; I do not see the sage.* classes like sage.Favorite that are referenced by the api classes.

[stuckless]

The Sage API Javadoc is a "Ficticious" api. It's what the API would look like, if it were actually provided. (I realize that doesn't make much sense, but the Sage Javadoc does not document "real" classes")

Look at the example in the package summary.

You'll see if you wanted to call MediaFileAPI.GetMediaFiles(), you'd actually call

Object[] mediaFiles = (Object[])sage.SageTV.api("GetMediaFiles", null);

Think of the documentted "java" api as a list of services that sagetv exposes, and if you want to use any of those services, then you actualy use the sage.SageTV.api() service call, passing in the servicename, and service arguments. Since all Sage Servicenames (static method names) are unique, then you DO NOT pass in the Class name that defines the service. ie, when you call the MediaFileAPI.GetMediaFiles(), you only pass in "GetMediaFiles" as the servicename, and not "MediaFileAPI.GetMediaFiles".

Hope this makes some sense.

[MeInMaui]

Check out GKusnick's Studio Tools. He has generated a complete set of Java wrappers for the SageTV API and has the Javadocs included in the download.

Aloha,
Mike

[Surtr]

Cool, thanks for the info guys. Just as an FYI, I want to write some utilities to manipulate sage from outside of SageTV, probably through a cron job. For instance, I want to clear the watched flag and delete a specific recorded show daily at 4:55 PM.

Will these APIs allow me to do this, or will the only run inside an STV?

Thanks!

-Justin

[MeInMaui]

Originally Posted by Surtr

Cool, thanks for the info guys. Just as an FYI, I want to write some utilities to manipulate sage from outside of SageTV, probably through a cron job. For instance, I want to clear the watched flag and delete a specific recorded show daily at 4:55 PM.

Will these APIs allow me to do this, or will the only run inside an STV?

Thanks!

-Justin

You can call SageTV API methods from an external Java program (see stuckless' post a few up), but it is much easier with GKusnick's wrappers. Check out his documentation and you will see.

Aloha,
Mike

[dflachbart]

Originally Posted by MeInMaui

You can call SageTV API methods from an external Java program (see stuckless' post a few up), but it is much easier with GKusnick's wrappers. Check out his documentation and you will see.

Aloha,
Mike

Actually, you can't call Sage API methods from an 'external' java program. Of course I know what you meant (calling the API from java code that gets loaded by SageTV at runtime) , but Justin's idea to use API calls in a separate program (with its own JVM) will not work...

The only way to achieve this would be to establish a custom thread within SageTV that would 'listen' to commands from an external program, e.g. like Niel's webserver ...

Dirk

[MeInMaui]

Originally Posted by flachbar

Actually, you can't call Sage API methods from an 'external' java program. Of course I know what you meant (calling the API from java code that gets loaded by SageTV at runtime) , but Justin's idea to use API calls in a separate program (with its own JVM) will not work...

The only way to achieve this would be to establish a custom thread within SageTV that would 'listen' to commands from an external program, e.g. like Niel's webserver ...

Dirk

Doh! I guess I have to watch it with those assumptions....

[stuckless]

Cool, thanks for the info guys. Just as an FYI, I want to write some utilities to manipulate sage from outside of SageTV, probably through a cron job. For instance, I want to clear the watched flag and delete a specific recorded show daily at 4:55 PM.

It's interesting you should mention that.... I just finished a sage service that exposes ALL of sage's API as RPC service calls.

So, in a separate jvm, I can run code like this...

		File[] libDirs = Configuration.GetLibraryImportPaths();
		if (libDirs!=null) {
			for (File f : libDirs) {
				System.out.println("Library import dir: " + f.getAbsolutePath());
			}
		}

And behind the scenes it dispatches all requests to the sage server and send back the responses. The API itself is auto generated from Sage's Javadocs, so you haves access to the complete sagetv api from another java process.

And no I haven't released the API as of yet. I will, but I only finished the main part of it today, so it's not quite ready for release.

As a side note to the API, you can transparently move the your code from being embedded within sage, to another jvm without have to recompile or change your code. So, if you start off developing code within Sage, you can later move it to another process... or if you start of writing code in another jvm process... you can later movet hat code to run within sage.

[Surtr]

Awesome stuckless! Anxiously awaiting your sw release!

[GKusnick]

Originally Posted by stuckless

The API itself is auto generated from Sage's Javadocs...

This is how my API wrappers are generated as well (but without the RPC part of course).

I'm wondering if it would make sense to pool our efforts, perhaps by implementing your RPC wrappers as a subclass of my API wrapper class, so that existing code that uses my wrappers can be easily ported to your RPC wrappers just by invoking a different constructor for the API object. If we're going to have two sets of API wrappers in circulation, it seems like it might be a good idea if they obey a common interface.

Getting back to the main topic, it seems like it wouldn't be hard to write a script to pull down the online docs page by page to a local directory. This is in essence what the wrapper generators do.

[dflachbart]

Originally Posted by GKusnick

I'm wondering if it would make sense to pool our efforts, perhaps by implementing your RPC wrappers as a subclass of my API wrapper class, so that existing code that uses my wrappers can be easily ported to your RPC wrappers just by invoking a different constructor for the API object. If we're going to have two sets of API wrappers in circulation, it seems like it might be a good idea if they obey a common interface.

Good idea, Greg. I totally agree, this would really make sense.


Dirk

[stuckless]

I'm wondering if it would make sense to pool our efforts, perhaps by implementing your RPC wrappers as a subclass of my API wrapper class, so that existing code that uses my wrappers can be easily ported to your RPC wrappers just by invoking a different constructor for the API object. If we're going to have two sets of API wrappers in circulation, it seems like it might be a good idea if they obey a common interface.

Greg, I don't want to hijack this thread too much I don't have any issues pooling together... I will point out that our api's are fundamentally different. I wanted to generate an API that represented the javadoc that sage built, exactly. What that means is that all of my "user facing" APIs are Static, as the javadoc shows. It also means that no extra objects are created since I don't wrap the sage objects being passed or comming back, (the exception being when the api is used in a remote mode, I do have to create some object references). All that being said, my api has 3 layers, with the final layer being the part that either talks to sage directly or remotely. So, it would be trivial for you to add the rpc portion of the api to your api. Although, I'll be honest, other than myself and the individual who posted earlier, I'm not sure a remote api is in large demand.

I did go looking for your generator some time ago... but i didn't find it with your tools download, so i assumed that you closed sourced it. It think if we are going to discuss this further we should either do it offline or in a dedicated "SageTV API" thread, so that we don't hijack this one any further.

[Surtr]

Hey guys -

Stuckless, your API works very well. Had it up and running in minutes. After looking at some of this stuff it looks like I can do what I need to do by including something in the sageTV server runtime as a startup class, or by doing what I was initially planning on doing (external cron job) with Stuckless' API.

Quick question, does anyone know how the mediaMask parameter on MediaFileAPI.GetMediaFiles() works? I don't see any reference to it in the documentation so have no clue what to pass for a mask value.

I was planning on looking up TV recordings for "NFL Total Access"; and so far the only way I see to do this is to look up all media files (that's a lot) with the MediaFileAPI and iterate over those that match IsTVFile(). Is there a way to look up media files by Favorite?

Fun stuff!

-Justin

[GKusnick]

Originally Posted by Surtr

I was planning on looking up TV recordings for "NFL Total Access"; and so far the only way I see to do this is to look up all media files (that's a lot) with the MediaFileAPI and iterate over those that match IsTVFile(). Is there a way to look up media files by Favorite?

Seems like some combination of GetFavoriteAirings, FilterByMethod, and GetMediaFileForAiring ought to do it for you.

[stuckless]

I found this post by Andy.

Database.SearchForTitles("NFL Total Access","T");

See Database.SearchForTitles

[Surtr]

You guys are awesome.

[Surtr]

Hey guys, I've got it working; I implemented it as a simple java app that finds local recordings of NFL Total Access, clears the watched flag and deletes the file. I'll just drop it as a cron job on my linux box and I'm all set. Stuckless, your API works flawlessly. Thanks for all the help everyone! Just gotta find some cool stuff to do with these APIs now.