Entity type abstract class

[beoliver]

As far as I am aware there is no abstract class or interface for an Entity. As these objects only return data it would be nice to be able to test for them. I am working with clojure, and to return clojure maps I perform a recursive traversal of entity objects.

I would like to propose an abstract class that all Entity objects inherit from.

Currently the only way to test if an object is an "entity" - ie it is not a handle to a db nor is it a returned document (BaseDocument excepted) is an entity - is to get the package name from the object and compare it against "com.arangodb.entity".

Problem - For example a multiDocumentEntity may have DocumentCreateEntity or VPackSlice under the field documents - this is dependent on context - did the user insert multiple documents or get multiple documents etc... One approach currently is

(defn is-entity? [obj]
  (when obj
    (= "com.arangodb.entity" (-> obj class .getPackage .getName))))

But having to extract package information (and hope that it is correct) is not ideal.

[mvollmary]

Hi @beoliver,

thanks for your feedback. I added an interface Entity. The change will be included in the next release.

best
Mark

[beoliver]

Hi @mpv1989,
great stuff!
To give a little more insight -
For the clojure wrapper lib that I am working on I have taken the following approach -

Objects that should remain as objects: eg ArangoCollection and ArangoDatabase as they are treated as handles - they are simply wrapped by giving their public methods lisp-like names i.e cammelCase becomes cammel-case

(defn ^ArangoCollection collection
  ([^ArangoDatabase db ^String coll-name]
   (.collection db coll-name)))

The question about entities is really a question of which objects can be treated as immutable data? for example all calls create,update,etc are wrapped with a function from-entity that allows the user of the library to dispatch on the class of the object. As a convenience I provide a default that checks that it is an entity and then converts it into a map structure (with the fields becoming the keys)

as an example

(defn ^DocumentCreateEntity insert-document
  ([^ArangoCollection coll ^Object doc]
   (ad/from-entity (.insertDocument coll (ad/serialize-doc doc))))
  ([^ArangoCollection coll ^Object doc ^DocumentCreateOptions options]
   (ad/from-entity (.insertDocument coll (ad/serialize-doc doc)
                                    (options/build DocumentCreateOptions options)))))

where ad/from-entity has the default implementation:

(defmethod from-entity :default [obj]
  ;; only some of the values will be entities
  (cond (is-entity? obj)
        ;; construct the entity recursively
        (try (.getDeclaringClass obj)
             ;; some entites only make sense as string
             ;; very much a heuristic here
             (str obj)
             (catch java.lang.IllegalArgumentException _
               (persistent!
                (reduce (fn [m [k v]]
                          (assoc! m k (from-entity v)))
                        (transient {}) (bean obj)))))
        ;; an array 'inside' an entity
        ;; we only map if we know the first item is an entity
        ;; this is because a MultiDocumententity may contain
        ;; return values or Entities depending on the call.
        (= java.util.ArrayList (-> obj class))
        (cond (empty? obj) []
              (is-entity? (.get obj 0)) (vec (map from-entity obj))
              :else (vec obj))
        :else obj))

It seems however that some of the entities contain setters - for example QueryCachePropertiesEntity has setMode and PathEntity has setEdges - while other entity-like objects (i.e they are in the package entities) like CollectionStatus or DocumentType only make sense (for the user) when calling string on the object (i.e "DOCUMENT" as opposed to {:type 2 :class CollectionType}.

Of course I could write a full destructuring algorithm that works on a Class by Class basis - but then this would obviously be fundamentally tied to the java implementation.

In my (and I appreciate that this is a very opinionated view) ideal world there would be:

1. An easy way to tell if an object is static DATA - meaning that It can be converted to something else without the user loosing any information or functionality - this can include objects that have nested objects as the whole thing can be traversed. So Objects with only fields and getters?
2. An easy way to tell if the object only makes sense (in a human readable way) if it is converted to a string. As mentioned at the moment I have found that if an object has the method .getDeclaringClass then it should be converted to a string.

I have written a separate serializer/deserializer for working with vpacks and clojure data structures - havn't got round to setting it up so it can be registered (I know that scala has one).

[christian-lechner]

1. An easy way to tell if an object is static DATA - meaning that It can be converted to something else without the user loosing any information or functionality - this can include objects that have nested objects as the whole thing can be traversed. So Objects with only fields and getters?

Classes inside com.arangodb.entity can be considered immutable, although they have setter methods. These classes are only used as return values (the setters are used by the deserializer). So, even if users change the returned entities, they can't be passed back to the driver.
Classes inside com.arangodb.model are created by users and passed to the driver.

2. An easy way to tell if the object only makes sense (in a human readable way) if it is converted to a string. As mentioned at the moment I have found that if an object has the method .getDeclaringClass then it should be converted to a string.

As you mentioned CollectionStatus and CollectionType, I think you are talking about Enums. In order to check if a class only makes sense as a string, can't you just do sth. like (instance? java.lang.Enum obj)?

[beoliver]

@christian-lechner - great - and yes, if they are only enums then just having the exta interface Entity is perfect. This would mean that the values of an Entity are Enity Enum Array.List of something that be recursively checked or java.classes like boolean, string, int etc.

[christian-lechner]

Entity classes can also have static inner classes like AqlParseEntity.

[mvollmary]

I released version 4.7.0 which includes a Entity marker interface