votorola.g

Class MediaWiki

java.lang.Object

MediaWiki

@ThreadSafe
public final class MediaWiki
extends Object

Utilities for communicating with the MediaWiki wiki system.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MediaWiki.APIError Thrown when a MediaWiki API call returns an explicit error response.
static class	MediaWiki.MalformedRequest Thrown when an improperly formed API call is detected.
static class	MediaWiki.MalformedResponse Thrown when the response to an API call is improperly formed.
static class	MediaWiki.NoSuchItem Thrown when a request cannot be met because an item does not exist.
static class	MediaWiki.NoSuchPage Thrown when a request cannot be met because a page does not exist.
static class	MediaWiki.NoSuchRev Thrown when a request cannot be met because a page revision does not exist.

Field Summary

Fields

Modifier and Type	Field and Description
static String	API_POST_CHARSET The character set for posting to the MediaWiki API.
static Pattern	MAYBE_UGLY_URL_PATTERN A pattern that detects whether a wiki URL might be based on the standard access URL ending in "index.php" for example, or is definitely based on a pretty alias per $wgUsePathInfo.

Method Summary

Methods

Modifier and Type	Method and Description
static StringBuilder	appendPageSpecifier(StringBuilder b, boolean maybeUgly, String encodedPageName) Appends an already encoded page name to a wiki base URL.
static String	demiDecodedPageName(String demiEncodedPageName) Completes the URL-decoding of a page name by substituting spaces for underscores.
static String	demiEncodedPageName(String unEncodedPageName, boolean maybeUgly) Partially encodes a page name prior to full URL-encoding, either by substituting underscores for spaces, or by doing the opposite if the wiki URL is ugly.
static javax.ws.rs.core.UriBuilder	encodePageSpecifier(javax.ws.rs.core.UriBuilder ub, boolean maybeUgly, String pageName) Encodes a page name and appends it to a wiki base URL.
static File	fetchPageAsFile(URI s, String idType, int id, String prefix) Downloads the wikitext source of the specified page into a temporary file.
static String	login(URI api, CookieHandler cookieHandler, String username, String password) Logs into a wiki.
static XMLStreamReader	newXMLStreamReader(InputStream in, Spool spool) Constructs a new stream reader suitable for reading a MediaWiki API response, and reads just to the 'api' element.
static String	normalUsername(String name) Translates the username to normal form by shifting the first letter to uppercase and substituting spaces for underscores.
static MatchResult	parsePageName(String pageName) Parses a page name (example "Ns:Root/sub/path") into two groups: (1) namespace "Ns", and (2) local name "Root/sub/path".
static MatchResult	parsePageNameS(String pageName) Parses a page name (example "Ns:Root/sub/path") into three groups: (1) namespace "Ns", (2) local root name "Root" and (3) subpage path "sub/path".
static com.google.gson.stream.JsonReader	requestJSON(URLConnection _http, Spool spool) Establishes an HTTP connection and returns a JSON reader for the response.
static XMLStreamReader	requestXML(URLConnection _http, Spool spool) Establishes an HTTP connection and returns an XML reader pre-situated on the 'api' element of the response body.
static String	revLoc(String scriptLoc, int rev) Constructs the URL for a page revision.
static String	revLoc(URI scriptURI, int _rev) Constructs the URL to a page revision.
static void	test_badrevids(XMLStreamReader r) Tests the current element of an API response and throws NoSuchRev if the element is named 'badrevids'.
static void	test_error(XMLStreamReader r) Tests the current element of an API response and throws an APIError if the element is named 'error'.
static void	testPage_missing(XMLStreamReader r) Tests the 'page' element of an API 'info' query response and throws NoSuchPage if it encodes a 'missing' attribute.

Methods inherited from class java.lang.Object

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

Field Detail

API_POST_CHARSET

public static final String API_POST_CHARSET

The character set for posting to the MediaWiki API.

See Also:

Constant Field Values

MAYBE_UGLY_URL_PATTERN

public static final Pattern MAYBE_UGLY_URL_PATTERN

A pattern that detects whether a wiki URL might be based on the standard access URL ending in "index.php" for example, or is definitely based on a pretty alias per $wgUsePathInfo.

Method Detail

appendPageSpecifier

public static StringBuilder appendPageSpecifier(StringBuilder b,
                                boolean maybeUgly,
                                String encodedPageName)

Appends an already encoded page name to a wiki base URL. The encoded page name (e.g. "Main_page") is appended as a simple path (/Main_page) if that is safe, otherwise as a title query (?title=Main_page).

Parameters:

b - a String builder containing only the wiki base URL, without a trailing slash (/).

maybeUgly - whether the base URL might be the standard access URL ending in "index.php" for example, or is definitely a pretty alias per $wgUsePathInfo.

Returns:

the same string builder with the page name appended.

See Also:

encodePageSpecifier(UriBuilder,boolean,String), MAYBE_UGLY_URL_PATTERN

demiDecodedPageName

public static String demiDecodedPageName(String demiEncodedPageName)

Completes the URL-decoding of a page name by substituting spaces for underscores.

See Also:

Help:Magic_words#Page_names

demiEncodedPageName

public static String demiEncodedPageName(String unEncodedPageName,
                         boolean maybeUgly)

Partially encodes a page name prior to full URL-encoding, either by substituting underscores for spaces, or by doing the opposite if the wiki URL is ugly. In that case, the page name will be used as a 'title' parameter and the removal of all demi-encoding is necessary for 'view' actions to be automatically redirected by the wiki to its pretty alias where one is actually available. (This despite the fact that the wiki itself demi-encodes the title parameter for actions such as 'edit' and 'history'.)

Parameters:

maybeUgly - whether the base URL might be the standard access URL ending in "index.php" for example, or is definitely a pretty alias per $wgUsePathInfo.

See Also:

Help:Magic_words#Page_names

encodePageSpecifier

public static javax.ws.rs.core.UriBuilder encodePageSpecifier(javax.ws.rs.core.UriBuilder ub,
                                              boolean maybeUgly,
                                              String pageName)

Encodes a page name and appends it to a wiki base URL. The page name (e.g. "Main page") is encoded and appended as a simple path (/Main_page) if that is safe, otherwise as a title query (?title=Main+page).

Parameters:

ub - a URI builder containing only the wiki base URL.

maybeUgly - whether the base URL might be the standard access URL ending in "index.php" for example, or is definitely a pretty alias per $wgUsePathInfo.

Returns:

the same URI builder with the page name encoded and appended.

See Also:

appendPageSpecifier(StringBuilder,boolean,String), MAYBE_UGLY_URL_PATTERN

fetchPageAsFile

public static File fetchPageAsFile(URI s,
                   String idType,
                   int id,
                   String prefix)
                            throws IOException

Downloads the wikitext source of the specified page into a temporary file.

Parameters:

idType - one of "curid" or "oldid".

id - the page identifier (curid) or revision identifier (oldid).

s - the base URL for script execution in the wiki, without a trailing slash (/).

prefix - the prefix for the temporary file.

Throws:

IOException

See Also:

www.mediawiki.org/wiki/Manual:Parameters_to_index.php

login

public static String login(URI api,
           CookieHandler cookieHandler,
           String username,
           String password)
                    throws IOException

Logs into a wiki.

Parameters:

api - the URL of the wiki's api.php script.

Returns:

error message for any failure that might be user actionable, such as an incorrect password; or null if login succeeds.

Throws:

IOException

newXMLStreamReader

@ThreadSafe
public static XMLStreamReader newXMLStreamReader(InputStream in,
                                            Spool spool)
                                          throws IOException,
                                                 XMLStreamException

Constructs a new stream reader suitable for reading a MediaWiki API response, and reads just to the 'api' element.

Parameters:

spool - an optional spool for the release of associated holds. When unwound it releases the holds of the reader and thereby disables it.

Throws:

IOException

XMLStreamException

See Also:

requestXML(URLConnection,Spool)

normalUsername

public static String normalUsername(String name)

Translates the username to normal form by shifting the first letter to uppercase and substituting spaces for underscores.

Returns:

the translated name, which may be the same name; or null if the name is null.

parsePageName

public static MatchResult parsePageName(String pageName)

Parses a page name (example "Ns:Root/sub/path") into two groups: (1) namespace "Ns", and (2) local name "Root/sub/path". The namespace group will be null if not present. Note that group values may have underscores from demi-encoding, depending on where the provided name string was constructed.

See Also:

Help:Magic_word#Page_names

parsePageNameS

public static MatchResult parsePageNameS(String pageName)

Parses a page name (example "Ns:Root/sub/path") into three groups: (1) namespace "Ns", (2) local root name "Root" and (3) subpage path "sub/path". The namespace group will be null if not present, likewise for the subpage path. Note that group values may have underscores from demi-encoding, depending on where the provided name string was constructed.

See Also:

Help:Magic_word#Page_names

requestJSON

public static com.google.gson.stream.JsonReader requestJSON(URLConnection _http,
                                            Spool spool)
                                                     throws IOException

Establishes an HTTP connection and returns a JSON reader for the response.

Parameters:

_http - the connector, which must be of type HttpURLConnection. The base class is accepted only as a convenience to save clients having to cast the result of URL.openConnection().

spool - a spool for the release of associated holds. When unwound it releases the holds of the reader and thereby disables it.

Throws:

IOException

requestXML

public static XMLStreamReader requestXML(URLConnection _http,
                         Spool spool)
                                  throws IOException,
                                         XMLStreamException

Establishes an HTTP connection and returns an XML reader pre-situated on the 'api' element of the response body.

Parameters:

_http - the connector, which must be of type HttpURLConnection. The base class is accepted only as a convenience to save clients having to cast the result of URL.openConnection().

spool - a spool for the release of associated holds. When unwound it releases the holds of the reader and thereby disables it.

Throws:

IOException

XMLStreamException

revLoc

public static String revLoc(String scriptLoc,
            int rev)

Constructs the URL for a page revision.

Parameters:

scriptLoc - the base location for script execution in the wiki, without a trailing slash (/).

revLoc

public static String revLoc(URI scriptURI,
            int _rev)

Constructs the URL to a page revision.

Parameters:

scriptURI - the base location for script execution in the wiki, without a trailing slash (/).

test_badrevids

public static void test_badrevids(XMLStreamReader r)
                           throws MediaWiki.NoSuchRev,
                                  XMLStreamException

Tests the current element of an API response and throws NoSuchRev if the element is named 'badrevids'. The 'badrevids' element is undocumented in the API (2010-11).

Parameters:

r - a reader positioned at an element start tag.

Throws:

MediaWiki.NoSuchRev

XMLStreamException

test_error

public static void test_error(XMLStreamReader r)
                       throws MediaWiki.APIError

Tests the current element of an API response and throws an APIError if the element is named 'error'.

Parameters:

r - a reader positioned at an element start tag.

Throws:

MediaWiki.APIError

See Also:

API:Errors_and_warnings#Errors

testPage_missing

public static void testPage_missing(XMLStreamReader r)
                             throws MediaWiki.NoSuchPage

Tests the 'page' element of an API 'info' query response and throws NoSuchPage if it encodes a 'missing' attribute. Works for queries that specify a 'titles' parameter, but not a 'revids' parameter (MediaWiki 1.15.1). For 'revids', use instead test_badrevids.

Parameters:

r - a reader positioned at a 'page' element start tag.

Throws:

MediaWiki.NoSuchPage - if the response indicates a missing page.

MediaWiki.MalformedRequest - if the response indicates an invalid page name.

See Also:

API:Query#Missing_and_invalid_titles