Package 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	Description
StudIPAPI(String consumerKey, String consumerSecret)	Initializes a new StudIPAPI instance.

Method Summary

Modifier and Type	Method	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.
Folder	getCourseTopFolder(String courseID)	Returns the top folder object of the searched course.
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.
Folder	getFolder(String folderID)	Returns the searched folder object for the given folder ID.
de.femtopedia.studip.shib.OAuthClient	getOAuthClient()	Returns the currently used OAuthClient instance.
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	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 Details

StudIPAPI

public StudIPAPI(String consumerKey,
 String consumerSecret)

Initializes a new StudIPAPI instance.

Parameters:

consumerKey - The Consumer Key to use

consumerSecret - The Consumer Secret to use

Method Details

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 second 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 is 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

getCourseTopFolder

public Folder getCourseTopFolder(String courseID)
                          throws IOException,
IllegalArgumentException,
IllegalAccessException,
oauth.signpost.exception.OAuthException

Returns the top folder object of the searched course.

Parameters:

courseID - The course to search for

Returns:

the parsed and converted Folder 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

getFolder

public Folder getFolder(String folderID)
                 throws IOException,
IllegalArgumentException,
IllegalAccessException,
oauth.signpost.exception.OAuthException

Returns the searched folder object for the given folder ID.

Parameters:

folderID - The folder to search for

Returns:

the parsed and converted Folder 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(String userID)
                     throws IOException,
IllegalArgumentException,
IllegalAccessException,
oauth.signpost.exception.OAuthException

Returns data about the currently logged in user's schedule.

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.

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