= jscribd

* 1.0 (June 11, 2010)

== DESCRIPTION:

jscribd is a Java library for interacting with the Scribd API. For more information on
the Scribd platform, visit http://www.scribd.com/developers/api

== FEATURES:

* Upload your documents to Scribd's servers
* Upload local files or from remote web sites
* Search, tag, and organize documents
* Associate documents with your users' accounts

== BUILDING (Ant users):

To build the jscribd jar, run:

  $ ant dist

You'll find the jar in:

  dist/jscribd-20110423.jar

... where '20110423' is YYYYMMDD build timestamp.

jscribd'd dependencies are downloaded and copied into:

  dist/lib

as part of this process.

== BUILDING (Maven users):

To build the artifact and install it in your local repository, run:

  $ ant artifact-install

Then add it as a dependency:

<dependency>
  <groupId>com.scribd</groupId>
  <artifactId>jscribd</artifactId>
  <version>1.0</version>
</dependency>

Make sure the version you use in your pom matches what was actually built, in
case this documentation gets out of date. If in doubt, check in dist/mvn/ .

== GETTING STARTED:

First, you'll need to get a Scribd API account. Visit
http://www.scribd.com/developers/api to apply for a platform account.

On the Platform site you will be given an API key and secret, which the API object
will need to authenticate you. 

You can pass your API key and secret into the ScribdApi constructor:

  Scribd scribd = new Scribd(new ScribdApi("[api-key]", "[api-secret]"));

Alternately you can setup the following environment variables, but this is
INSECURE and EXPOSES YOUR CREDENTIALS TO OTHER LOCAL USERS on many platforms:

  $ export SCRIBD_API_KEY=[api-key]
  $ export SCRIBD_API_SECRET=[api-secret]

  Scribd scribd = new Scribd();

Once your credentials are set up, log into Scribd:

  ScribdUser user = scribd.getApi().login("[username]", "[password]");

You are now ready to use Scribd to manage your documents. For instance, to
upload a document:

  Map<String, Object> attributes = new HashMap<String, Object>();
  attributes.put("access", "private");
  File file = new File("[path-to-file]");
  ScribdDocument uploadDoc = new ScribdDocument(scribd.getApi(), file, user, attributes);
  uploadDoc.save();

== REQUIREMENTS:

* A Scribd API account
* The libraries used by jscribd, as listed in build.xml's <artifact:pom> section
  * Ant users: after "ant dist" these can be found in dist/lib; add them to your project classpath
  * Maven users: Just depend on jscribd, maven does the rest

== TROUBLESHOOTING:

ant test: "the class org.apache.tools.ant.taskdefs.optional.junit.JUnitTask was not found."
Cause: Some Linux distibutions package ant-junit separately from ant. Ensure that the ant-junit
task is installed. On Fedora, you must have both the "ant" and "ant-junit" packages installed.