Doxygen

Doxyfile

@@ -0,0 +1,22 @@
+CREATE_SUBDIRS       = YES
+ALPHABETICAL_INDEX   = YES
+COLS_IN_ALPHA_INDEX  = 3
+GENERATE_HTML        = YES
+EXCLUDE_PATTERNS     = **/.git **/test **/target **/.settings **/resources **/com/twmacinta
+FILE_PATTERNS        = *.java
+INPUT                = audiobox.fm-core/src/main/java/fm audiobox.fm-sync/src/main/java/fm
+PROJECT_NAME         = AudioBox.fm Java Libs
+PROJECT_NUMBER       = 2.0-SNAPSHOT
+RECURSIVE            = YES
+OUTPUT_DIRECTORY     = target
+JAVADOC_AUTOBRIEF    = YES
+OPTIMIZE_OUTPUT_JAVA = YES
+EXTRACT_ALL          = YES
+GENERATE_TODOLIST    = YES
+QUIET                = YES
+WARNINGS             = NO
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR    = YES
+WARN_NO_PARAMDOC     = YES
+WARN_LOGFILE         = target/doxygen.log
+

audiobox.fm-core/src/main/java/fm/audiobox/AudioBox.java

@@ -28,6 +28,7 @@
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Observer;
 import java.util.zip.GZIPInputStream;
 
 import org.apache.http.Header;
@@ -67,17 +68,20 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import fm.audiobox.configurations.DefaultConfiguration;
+import fm.audiobox.configurations.DefaultFactory;
 import fm.audiobox.core.exceptions.LoginException;
 import fm.audiobox.core.exceptions.ServiceException;
+import fm.audiobox.core.models.AbstractCollectionEntity;
 import fm.audiobox.core.models.User;
 import fm.audiobox.interfaces.IConfiguration;
 import fm.audiobox.interfaces.IConnector;
 import fm.audiobox.interfaces.IEntity;
+import fm.audiobox.interfaces.IFactory;
 
 
 /**
  * AudioBox is the main library class. Every request to AudioBox.fm should pass through this object.
- * This class is used mainly to configure every aspect of the library itself.<br/>
  * To populate and get informations about user library use the {@link User} (or an extended User) model instead.
  * <p>
  * 
@@ -91,29 +95,32 @@
  *
  * <p>
  *
- * In order to make AudioBox load your extended models you will need to provide your {@link Model} extension
- * through the {@link AudioBox#setCollectionListenerFor(String, CollectionListener)} method.<br/>
+ * In order to make AudioBox load your extended models you will need to provide your {@link AbstractEntity} extension
+ * through an {@link IFactory#setEntity(String, Class)} implementation. If you don't want to implement one you can use
+ * the {@link DefaultFactory}.<br/>
  *
  * <p>
  * 
- * Note that some of the requests, such as the ModelsCollection population requests, can be done asynchronously.<br/>
- * To keep track of the collection building process you can make use of the {@link CollectionListener} object.
+ * Note that some of the requests, such as the {@link AbstractCollectionEntity} population requests, can be done 
+ * asynchronously.<br/>
+ * To keep track of the collection building process you can use {@link Observer Observers}.
  * 
  * <p>
  *
  * The usual execution flow can be demonstrated by the code snippet below:
  *
  * <pre>
+ * @code
+ * // With this object you can configure many aspects of the libs
+ * IConfiguration configuration = new DefaultConfiguration("My test application");
+ * 
  * // Creating the new AudioBox instance
- * abc = new AudioBox();
+ * abc = new AudioBox(configuration);
  *
  * // If you extended the {@link User} model AudioBox should 
  * // be informed before the login take place.
- * AudioBox.setModelClassFor(AudioBox.USER_KEY , MyUser.class );
+ * abc.getConfiguration().getFactory().setEntity(User.TAGNAME, MyUser.class);
  * 
- * // Suppose we want to limit requests timeout to 5 seconds
- * abc.getMainConnector().setTimeout( 5000 );
- *  
  * // Now we can try to perform a login...
  * try {
  *
@@ -124,12 +131,18 @@
  *    // To browse user library we have some nice utils methods
  *    // We can get the user's playlists...
  *    Playlists pls = user.getPlaylists();
+ *    // This object is still empty because you may want to add some observer to it or do 
+ *    // something else with it.
+ *    
+ *    // To populate the playlists call load method:
+ *    pls.load(false);
  *    
  *    // ...and get more details on a specific one
  *    Playlist pl = playlists.get(0);
  *    
  *    // Get playlist's tracks
  *    Tracks trs = pl.getTracks();
+ *    trs.load(false);
  *    
  *    // Track informations
  *    Track tr = trs.get(0);
@@ -139,14 +152,15 @@
  * } catch (ServiceException e) {
  *    // Handle {@link ServiceException}
  * }
+ * @endcode
  * </pre>
  *
  * This is briefly the navigation loop. Moreover each model offer some action that can be performed. To know what a model
  * can do consult the specific model documentation.
  * 
  * @author Valerio Chiodino
  * @author Fabio Tunno
- * @version 0.0.1
+ * @version 1.0.0
  */
 public class AudioBox {
 

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Album.java

@@ -39,8 +39,7 @@
  * Album XML looks like this: 
  * 
  * <pre>
- * {@code
- * 
+ * @code
  * <album>
  *   <name>Album name</name>
  *   <token>coq8FfgK</token>
@@ -54,7 +53,7 @@
  *     <token>fs8d8g9d</token>
  *   </artist>
  * </album>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Artist.java

@@ -39,12 +39,12 @@
  * Artist XML looks like this: 
  * 
  * <pre>
- * {@code
+ * @code
  * <artist>
  *   <name>Artist name</name>
  *   <token>cd8sa09df</token>
  * </artist>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Covers.java

@@ -39,13 +39,13 @@
  * CoverUrls XML looks like this: 
  * 
  * <pre>
- * {@code
- *   <covers> 
- *     <l>http://media.audiobox.fm/images/albums/HOBh1lMt/l.jpg?1277867432</l> 
- *     <m>http://media.audiobox.fm/images/albums/HOBh1lMt/m.jpg?1277867432</m> 
- *     <s>http://media.audiobox.fm/images/albums/HOBh1lMt/s.jpg?1277867432</s> 
- *   </covers>
- * }
+ * @code
+ * <covers> 
+ *   <l>http://media.audiobox.fm/images/albums/HOBh1lMt/l.jpg?1277867432</l> 
+ *   <m>http://media.audiobox.fm/images/albums/HOBh1lMt/m.jpg?1277867432</m> 
+ *   <s>http://media.audiobox.fm/images/albums/HOBh1lMt/s.jpg?1277867432</s> 
+ * </covers>
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Error.java

@@ -39,12 +39,12 @@
  * Error XML looks like this: 
  * 
  * <pre>
- * {@code
+ * @code
  * <error>
  *   <status>500</name>
  *   <message>This is an error message</token>
  * </error>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Genre.java

@@ -39,12 +39,12 @@
  * Genre XML looks like this: 
  * 
  * <pre>
- * {@code
+ * @code
  * <genre>
  *   <name>Genre name</name>
  *   <token>sjKzpds9Tk</token>
  * </genre>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Plan.java

@@ -38,20 +38,20 @@
  * Plan XML looks like this: 
  * 
  * <pre>
- * {@code
-   <plan>
-     <feat_api>true</feat_api> 
-     <feat_cloud_web_player>true</feat_cloud_web_player> 
-     <feat_dropbox>true</feat_dropbox> 
-     <feat_gigjunkie>true</feat_gigjunkie> 
-     <feat_lastfm>true</feat_lastfm> 
-     <feat_manager>true</feat_manager> 
-     <feat_multiformat>true</feat_multiformat> 
-     <feat_social_networks>true</feat_social_networks> 
-     <feat_youtube_channel>true</feat_youtube_channel> 
-     <name>plan</name>
-   </plan>
- * }
+ * @code
+ * <plan>
+ *  <feat_api>true</feat_api> 
+ *  <feat_cloud_web_player>true</feat_cloud_web_player> 
+ *  <feat_dropbox>true</feat_dropbox> 
+ *  <feat_gigjunkie>true</feat_gigjunkie> 
+ *  <feat_lastfm>true</feat_lastfm> 
+ *  <feat_manager>true</feat_manager> 
+ *  <feat_multiformat>true</feat_multiformat> 
+ *  <feat_social_networks>true</feat_social_networks> 
+ *  <feat_youtube_channel>true</feat_youtube_channel> 
+ *  <name>plan</name>
+ * </plan>
+ * @endcode
  * </pre>
  * 
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Playlist.java

@@ -59,15 +59,15 @@
  * Profile XML looks like this: 
  * 
  * <pre>
- * {@code
+ * @code
  * <playlist>
  *   <token>as89d7h4sa</token>
  *   <name>Music</name>
  *   <position>1</position>
  *   <playlist_type>audio</playlist_type>
  *   <playlist_tracks_count>12312</playlist_tracks_count>
  * </playlist>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Profile.java

@@ -39,12 +39,12 @@
  * Profile XML looks like this: 
  * 
  * <pre>
- * {@code
-   <profile> 
-     <autoplay>false</autoplay> 
-     <real_name>Name Surname</real_name> 
-   </profile>
- * }
+ * @code
+ * <profile> 
+ *   <autoplay>false</autoplay> 
+ *   <real_name>Name Surname</real_name> 
+ * </profile>
+ * @endcode
  * </pre>
  * 
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/Track.java

@@ -46,7 +46,7 @@
  * The XML response looks like this:
  *
  * <pre>
- * {@code
+ * @code
  * <track> 
  *   <token>{token}</token> 
  *   <title>Title</title> 
@@ -64,7 +64,7 @@
  *   <artist>...</artist> 
  *   <genre>...</genre> 
  * </track>
- * }
+ * @endcode
  * </pre>
  *
  * @author Valerio Chiodino

audiobox.fm-core/src/main/java/fm/audiobox/core/models/User.java

@@ -43,23 +43,22 @@
  * When a login is successfully performed an XML like the following is received and parsed:
  * 
  * <pre>
- * {@code
- * 
-   <user> 
-     <bytes_served>25352551153</bytes_served> 
-     <email>user@domain.com</email> 
-     <play_count>3378</play_count> 
-     <quota>1318739344</quota> 
-     <tracks_count>273</tracks_count> 
-     <username>username</username> 
-     <available_storage>162135015424</available_storage> 
-     <allowed_formats>aac;mp3;mp2;m4a;m4b;m4r;mp4;3gp;ogg;oga;flac;spx;wma;rm;ram;wav;mpc;mp+;mpp;aiff;aif;aifc;tta</allowed_formats> 
-     <time_zone>Rome</time_zone> 
-     <trial_ends_at>2011-03-05 08:20:38 +0100</trial_ends_at> 
-     <profile>....</profile>
-     <plan>...</plan>
-   </user>
- * }
+ * @code
+ * <user> 
+ *  <bytes_served>25352551153</bytes_served> 
+ *  <email>user@domain.com</email> 
+ *  <play_count>3378</play_count> 
+ *  <quota>1318739344</quota> 
+ *  <tracks_count>273</tracks_count> 
+ *  <username>username</username> 
+ *  <available_storage>162135015424</available_storage> 
+ *  <allowed_formats>aac;mp3;mp2;m4a;m4b;m4r;mp4;3gp;ogg;oga;flac;spx;wma;rm;ram;wav;mpc;mp+;mpp;aiff;aif;aifc;tta</allowed_formats> 
+ *  <time_zone>Rome</time_zone> 
+ *  <trial_ends_at>2011-03-05 08:20:38 +0100</trial_ends_at> 
+ *  <profile>....</profile>
+ *  <plan>...</plan>
+ * </user>
+ * @endcode
  * </pre>
  *
  * Through the User object you have access to its library that can be browsed by:

audiobox.fm-core/src/main/java/fm/audiobox/interfaces/IConfiguration.java

@@ -34,6 +34,8 @@
 import fm.audiobox.interfaces.IConnector.IConnectionMethod;
 
 /**
+ * This interface describes how an implementation of the AudioBox configuration should behave.<br/>
+ * An implementing class is mainly used to configure every aspect of the library itself.
  * 
  * @author Fabio Tunno
  */

audiobox.fm-core/src/main/java/fm/audiobox/interfaces/IFactory.java

@@ -16,15 +16,17 @@ public interface IFactory {
 
   /**
    * Sets the right entity associated with its default class
-   * @param klass default {@link Class}
-   * @param entity new {@link Class} to be instantiated
+   * 
+   * @param tagName the name of the tag to associate to the class
+   * @param entityClass new {@link Class} to be instantiated
    */
-  public void setEntity(String tagName, Class<? extends IEntity> entity);
+  public void setEntity(String tagName, Class<? extends IEntity> entityClass);
 
   /**
    * Returns true if an {@link IEntity} has been set
    * 
    * @param tagName the {@link IEntity} tag name
+   * 
    * @return true if an {@link IEntity} has been set
    */
   public boolean containsEntity(String tagName);