de.femtopedia.studip

Class StudIPAPI

java.lang.Object

de.femtopedia.studip.StudIPAPI

public class StudIPAPI
extends Object

A simple-to-use API class to access the Stud.IP RestAPI.

Constructor Summary

Constructors

Constructor and Description
StudIPAPI(String consumerKey, String consumerSecret) Initializes a new StudIPAPI instance with cookies.
StudIPAPI(String consumerKey, String consumerSecret, InputStream keyStore, String password) Initializes a new StudIPAPI instance with cookies and a custom KeyStore.

Method Summary

Modifier and Type	Method and Description
de.femtopedia.studip.shib.CustomAccessHttpResponse	get(String url) Performs a HTTP GET Request.
String	getAuthorizationUrl(String callback) Retrieves a Request Token and returns a authorization URL, which you have to open in a browser and approve access to your account.
Contacts	getContacts(String userID) Returns data about the searched user's contacts.
Course	getCourse(String courseID) Returns data about the searched course.
Courses	getCourses(String userID) Returns data about the searched user's courses.
User	getCurrentUserData() Returns the currently logged in user's data.
<T> T	getData(String apiUrl, Class<T> objClass) Performs a HTTP GET Request and converts the site's content into the given Object type using Gson.
Events	getEvents(String userID) Returns data about the searched user's events.
de.femtopedia.studip.shib.OAuthClient	getOAuthClient() Returns the currently used OAuthClient instance.
Schedule	getSchedule() Returns data about the currently logged in user's schedule.
Schedule	getSchedule(String userID) Returns data about the currently logged in user's schedule.
Schedule	getSchedule(String userID, String semesterID) Returns data about the currently logged in user's schedule.
Semester	getSemester(String semesterID) Returns data about the searched semester.
Semesters	getSemesters() Returns data about all semesters.
User	getUserData(String userID) Returns data about the searched user.
boolean	isSessionValid() Returns, whether the current session is valid or you need to re-login.
void	shutdown() Shuts down the OAuthClient.
void	verifyAccess(String verifyToken) Retrieves a working Access Token and saves it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StudIPAPI

public StudIPAPI(String consumerKey,
                 String consumerSecret)

Initializes a new StudIPAPI instance with cookies.

Parameters:

consumerKey - The Consumer Key to use

consumerSecret - The Consumer Secret to use

StudIPAPI

public StudIPAPI(String consumerKey,
                 String consumerSecret,
                 InputStream keyStore,
                 String password)

Initializes a new StudIPAPI instance with cookies and a custom KeyStore.

Parameters:

consumerKey - The Consumer Key to use

consumerSecret - The Consumer Secret to use

keyStore - A custom KeyStore as InputStream to set or null

password - The KeyStore's password

Method Detail

getAuthorizationUrl

public String getAuthorizationUrl(String callback)
                           throws oauth.signpost.exception.OAuthException

Retrieves a Request Token and returns a authorization URL, which you have to open in a browser and approve access to your account. This is the first function to call in the OAuth process.

Parameters:

callback - A callback URI or OAuth.OUT_OF_BAND.

Returns:

The Authorization URL to call

Throws:

oauth.signpost.exception.OAuthException - if any OAuth errors occur

verifyAccess

public void verifyAccess(String verifyToken)
                  throws oauth.signpost.exception.OAuthException

Retrieves a working Access Token and saves it. This is the third function to call in the OAuth process (call getAuthorizationUrl(String) first and authorize in a browser).

Parameters:

verifyToken - The Verification Code from the Authorization process.

Throws:

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getOAuthClient

public de.femtopedia.studip.shib.OAuthClient getOAuthClient()

Returns the currently used OAuthClient instance.

Returns:

the currently used OAuthClient instance

isSessionValid

public boolean isSessionValid()
                       throws IOException,
                              oauth.signpost.exception.OAuthException

Returns, whether the current session is valid or you need to re-login.

Returns:

true if and only if the current session cookies are valid

Throws:

IOException - if reading errors occur

oauth.signpost.exception.OAuthException - if any OAuth errors occur

get

public de.femtopedia.studip.shib.CustomAccessHttpResponse get(String url)
                                                       throws IOException,
                                                              IllegalArgumentException,
                                                              IllegalAccessException,
                                                              oauth.signpost.exception.OAuthException

Performs a HTTP GET Request.

Parameters:

url - The URL to get

Returns:

A CustomAccessHttpResponse representing the result

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getData

public <T> T getData(String apiUrl,
                     Class<T> objClass)
              throws IOException,
                     IllegalArgumentException,
                     IllegalAccessException,
                     oauth.signpost.exception.OAuthException

Performs a HTTP GET Request and converts the site's content into the given Object type using Gson.

Type Parameters:

T - The wanted Generic type

Parameters:

apiUrl - The URL to get

objClass - The class to cast to

Returns:

the parsed and converted object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getCurrentUserData

public User getCurrentUserData()
                        throws IOException,
                               IllegalArgumentException,
                               IllegalAccessException,
                               oauth.signpost.exception.OAuthException

Returns the currently logged in user's data.

Returns:

the parsed and converted User object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getUserData

public User getUserData(String userID)
                 throws IOException,
                        IllegalArgumentException,
                        IllegalAccessException,
                        oauth.signpost.exception.OAuthException

Returns data about the searched user.

Parameters:

userID - The user to search for

Returns:

the parsed and converted User object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getContacts

public Contacts getContacts(String userID)
                     throws IOException,
                            IllegalArgumentException,
                            IllegalAccessException,
                            oauth.signpost.exception.OAuthException

Returns data about the searched user's contacts.

Parameters:

userID - The user to search for

Returns:

the parsed and converted Contacts object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getEvents

public Events getEvents(String userID)
                 throws IOException,
                        IllegalArgumentException,
                        IllegalAccessException,
                        oauth.signpost.exception.OAuthException

Returns data about the searched user's events.

Parameters:

userID - The user to search for

Returns:

the parsed and converted Events object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getCourse

public Course getCourse(String courseID)
                 throws IOException,
                        IllegalArgumentException,
                        IllegalAccessException,
                        oauth.signpost.exception.OAuthException

Returns data about the searched course.

Parameters:

courseID - The course to search for

Returns:

the parsed and converted Course object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getCourses

public Courses getCourses(String userID)
                   throws IOException,
                          IllegalArgumentException,
                          IllegalAccessException,
                          oauth.signpost.exception.OAuthException

Returns data about the searched user's courses.

Parameters:

userID - The user to search for

Returns:

the parsed and converted Courses object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getSemesters

public Semesters getSemesters()
                       throws IOException,
                              IllegalArgumentException,
                              IllegalAccessException,
                              oauth.signpost.exception.OAuthException

Returns data about all semesters.

Returns:

the parsed and converted Semesters object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getSemester

public Semester getSemester(String semesterID)
                     throws IOException,
                            IllegalArgumentException,
                            IllegalAccessException,
                            oauth.signpost.exception.OAuthException

Returns data about the searched semester.

Parameters:

semesterID - The semester to search for

Returns:

the parsed and converted Semester object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getSchedule

public Schedule getSchedule()
                     throws IOException,
                            IllegalArgumentException,
                            IllegalAccessException,
                            oauth.signpost.exception.OAuthException

Returns data about the currently logged in user's schedule. THIS METHOD WILL GET REMOVED, WHEN THE RESTAPI SCHEDULE IS FIXED. THIS IS A TEMPORARY METHOD, THAT HARDCODED PARSES THE HTML TEXT. IT'S VERY UNSAFE AND CAN BREAK EASILY!!!

Returns:

the parsed and converted Schedule object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getSchedule

public Schedule getSchedule(String userID)
                     throws IOException,
                            IllegalArgumentException,
                            IllegalAccessException,
                            oauth.signpost.exception.OAuthException

Returns data about the currently logged in user's schedule. NOT FUNCTIONAL RIGHT NOW, BECAUSE OF PROBLEMS WITH THE RESTAPI. USE getSchedule() INSTEAD UNTIL THE PROBLEM IS FIXED!

Parameters:

userID - The user to search for

Returns:

the parsed and converted Schedule object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

getSchedule

public Schedule getSchedule(String userID,
                            String semesterID)
                     throws IOException,
                            IllegalArgumentException,
                            IllegalAccessException,
                            oauth.signpost.exception.OAuthException

Returns data about the currently logged in user's schedule. NOT FUNCTIONAL RIGHT NOW, BECAUSE OF PROBLEMS WITH THE RESTAPI. USE getSchedule() INSTEAD UNTIL THE PROBLEM IS FIXED!

Parameters:

userID - The user to search for

semesterID - The semester to search for

Returns:

the parsed and converted Schedule object

Throws:

IOException - if reading errors occur

IllegalArgumentException - if the header values are broken

IllegalAccessException - if the session isn't valid

oauth.signpost.exception.OAuthException - if any OAuth errors occur

shutdown

public void shutdown()

Shuts down the OAuthClient.