* Note that there is a avaje-ebeanorm-mocker project that enables you to use Mockito or similar
* tools to still mock out the underlying 'default EbeanServer' for testing purposes.
+ *
+ *
+ * You may choose not use this Model mapped superclass if you don't like the 'Active Record' style
+ * or if you believe it 'pollutes' your entity beans.
+ *
+ *
+ * If you choose to use the Model mapped superclass you will probably also chose to additionally add
+ * a {@link Finder} as a public static field to complete the active record pattern and provide a
+ * relatively nice clean way to write queries.
*/
@MappedSuperclass
public class Model {
- private Object _getId() {
- try {
- return db().getBeanId(this);
- } catch (RuntimeException e) {
- throw e;
- } catch (Exception e) {
- throw new RuntimeException(e);
- }
- }
-
/**
* Return the underlying 'default' EbeanServer.
*
@@ -45,7 +45,11 @@ public class Model {
}
/**
- * Return typically a different EbeanServer to the default.
+ * Return a named EbeanServer that is typically different to the default server.
+ *
+ *
+ * If you are using multiple databases then each database has a name and maps to a single
+ * EbeanServer. You can use this method to get an EbeanServer for another database.
*
* @param server
* The name of the EbeanServer. If this is null then the default EbeanServer is returned.
@@ -80,28 +84,28 @@ public class Model {
}
/**
- * Deletes this entity.
+ * Delete this entity.
*/
public void delete() {
db().delete(this);
}
/**
- * Update this entity.
+ * Perform an update using this entity against the specified server.
*/
public void update(String server) {
db(server).update(this);
}
/**
- * Insert this entity.
+ * Perform an insert using this entity against the specified server.
*/
public void insert(String server) {
db(server).insert(this);
}
/**
- * Deletes this entity.
+ * Perform a delete using this entity against the specified server.
*/
public void delete(String server) {
db(server).delete(this);
@@ -114,36 +118,19 @@ public class Model {
db().refresh(this);
}
- @Override
- public boolean equals(Object other) {
- // RB: This is inconsistent with the default Ebean implementation so
- // in that sense I don't believe this can be the default implementation
- if (this == other)
- return true;
- if (other == null || other.getClass() != this.getClass())
- return false;
- Object id = _getId();
- Object otherId = ((Model) other)._getId();
- if (id == null)
- return false;
- if (otherId == null)
- return false;
- return id.equals(otherId);
- }
-
- @Override
- public int hashCode() {
- // RB: this hashCode changes ... so I don't like this as the
- // baked in default behaviour - but need to support this for any Play users
- // that convert over to this. Best option is to support this in enhancement and let the
- // users choose their poison. Alternatively provide 2 versions of Model with the
- // 2 different behaviours for hashCode / equals
- Object id = _getId();
- return id == null ? super.hashCode() : id.hashCode();
- }
-
/**
- * Helper for queries.
+ * Helper object for performing queries.
+ *
+ *
+ * Typically a Finder is defined as a public static field on an entity bean class to provide a
+ * nice way to write queries.
+ *
+ * @param I
+ * The Id type. This is most often a {@link Long} but is also often a {@link UUID} or
+ * {@link String}.
+ *
+ * @param T
+ * The bean type
*/
public static class Finder {
@@ -163,7 +150,7 @@ public class Model {
/**
* Creates a finder for entity of type T with ID of type I, using a
- * specific Ebean server.
+ * specific EbeanServer.
*
*
* Typically you don't need to use this method.
@@ -179,6 +166,7 @@ public class Model {
*
*
* This provides full access to the API such as explicit transaction demarcation etc.
+ *
*/
public EbeanServer db() {
return Ebean.getServer(serverName);
@@ -186,6 +174,8 @@ public class Model {
/**
* Return typically a different EbeanServer to the default.
+ *
+ * This is equivilent to {@link Ebean#getServer(String)}
*
* @param server
* The name of the EbeanServer. If this is null then the default EbeanServer is
@@ -196,7 +186,7 @@ public class Model {
}
/**
- * Changes the Ebean server.
+ * Creates a Finder for the named EbeanServer.
*
*
* Create and return a new Finder for a different server.
@@ -222,6 +212,9 @@ public class Model {
/**
* Retrieves an entity by ID.
+ *
+ *
+ * Equivilent to {@link EbeanServer#find(Class, Object)}
*/
public T byId(I id) {
return db().find(type, id);
@@ -229,6 +222,9 @@ public class Model {
/**
* Creates an entity reference for this ID.
+ *
+ *
+ * Equivilent to {@link EbeanServer#getReference(Class, Object)}
*/
public T ref(I id) {
return db().getReference(type, id);
@@ -237,6 +233,8 @@ public class Model {
/**
* Creates a filter for sorting and filtering lists of entities locally without going back to
* the database.
+ *
+ * Equivilent to {@link EbeanServer#filter(Class)}
*/
public Filter filter() {
return db().filter(type);
@@ -244,6 +242,8 @@ public class Model {
/**
* Creates a query.
+ *
+ * Equivilent to {@link EbeanServer#find(Class)}
*/
public Query query() {
return db().find(type);
@@ -251,24 +251,18 @@ public class Model {
/**
* Returns the next identity value.
+ *
+ * @see EbeanServer#nextId(Class)
*/
@SuppressWarnings("unchecked")
public I nextId() {
return (I) db().nextId(type);
}
- /**
- * Executes a find IDs query in a background thread.
- *
- * @deprecated RB: Hmm, this is a "find all" - less is more, prefer to hide this - just get from
- * query().
- */
- public FutureIds findFutureIds() {
- return query().findFutureIds();
- }
-
/**
* Executes a query and returns the results as a list of IDs.
+ *
+ * Equivilent to {@link Query#findIds()}
*/
public List