DAM API Design Notes

Still under consideration

• AssetProvider should be queried - "can you handle this ItemKey?”, rather than “forcing” the AssetProvider to handle the key, by comparing it with its providerID
• Queries: client code could do assetProvider.newQuery() - this would return Query”Builder" - and then call execute() on this (which would probably internally callback the provider)
• Queries: adding arbitrary Predicate (Guava and Commons) to a query might be added as a feature to QueryBuilder so that client code doesn't have to do it. OTOH, all features on the AssetQuery currently allow for (potential) optimizations by the AssetProvider, whereas arbitrary predicates would most likely mean those have to be done after the "remote" query returns. Perhaps it's wiser to keep those outside AssetProvider to avoid misunderstandings as to what criteria is used where.
• DelegatingAssetProvider, AggregatingAssetProvider - could probably be implemented thanks to the fact we pass AssetKey (almost) everywhere. Currently not implemented to avoid the questions of what to do with unsupported features on a single provider (ignore or reject), etc. Also, while an AggregatingAssetProvider sounds tempting to do federated search, current UI sketches show that we'd anyway group the results by provider (or some notion that's close to that). Letting the UI (or some intermediary) call each provider on independently would allow for asynchronous display of results (show up the JCR results while the slower CMIS is still loading)
• If the "laziness" of  Item/Folder/Asset mentioned was to cause issues (which is perhaps going to be the case with templating etc), I would recommend the following:
  
  • implement a DisconnectedAsset class (or AssetDTO, or...) which
  • eagerly copies the properties of a given Asset into its fields,
  • refuses to provide an InputStream (in 1.x, the stream was always opened, and 99% never closed)
  • think a little longer about what to do if we also need this for folders 
    
    • perhaps a more restricted interface will be needed on Folder, and/or some methods moved out of Folder back to the AssetProvider.
  • ditto for MetaData. Perhaps the "copier" will need to take a list of MetaData that needs to be "copied" with the asset.

Using inner static classes for Exception (especially RuntimeExceptions) to avoid polluting the package (so every case can throw its own specific exception with its own specific constructor, without having to build String messages all over the place - ideally they shouldn't even be instantiable outside the implementations of the interfaces that declare them but i haven't figure that out yet)

Introduce a parent exception class ? (also runtime?)

+ // TODO I'm not keen on having this, as it would allow implementations to actually CHANGE their name.
+    // Force using class name as the identified ?
+    // TODO think about requirement of extensibility - plug in custom metadata suppliers
+    //
+   // String getName();

import com.google.common.base.CaseFormat;
public abstract class AbstractAssetMetadata implements AssetMetadata {
    //@Override
    public String getName() {
        return CaseFormat.UPPER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, this.getClass().getSimpleName());
    }
}
 
 
        assertEquals("my_meta_thing", new MyMetaThing().getName());

Write operations or CRUD thoughts

• See mention of write operations above
• We need to take a few more operations into account
• BREAD for "Browse, Read, Edit, Add, Delete" or CRUDL (L for Listing)
• IMO, for such a hierarchical system, Move is not Update.
• Version (some providers might have a versionOnUpdate configuration item, but we maybe want a "manual", "create version now" type of operation
• MADVERB 
• BUT: do we really need this ?
  
  • It may seem like a no-brainer at first sight ("be consistent"), but maybe we can reframe the need for an API. What do we really need the API for writing assets ?
    
    • Browsing jcr-based assets in the same way we browse external assets (the app)
    • Use or reference assets from any of source in a unified manner (the read api, the choose dialog, the templating functions)
    • I question the need for a unified API for creating assets because... if those assets are external, they presumably pre-exist Magnolia and/or are managed by different entities (software, people).
      
      • Would you upload a Youtube video through Magnolia, or through Youtube's very specialized UI ?
      • Would you upload a document through Magnolia's FileServer-AssetProvider, or by dragging and dropping it on your fileserver in Finder.app ?
      • I'm sure there are good cases / use-cases for this. But I only see two clients of such a writable-dam-api: the DAM App, and REST services.
        
        • I even see less of a point to upload-to-external-dam-through-Magnolia-REST. Presumably, your external DAM has a good reason to be in the system, and one of those is probably because it integrates well with whatever you'd be using the rest api instead ?
        • This leaves us with a few external DAMs that do need to have write-ops in Magnolia:
          
          • Is the dam app really the best UI for those ? Maybe the external dam provides its own UI, or at least a paradigm where a tree or a flat list don't really match what we're looking for (some DAMs are better suited to have a search-only or tag-based browsing interface)
          • What is the real benefit (time/cost) of generalizing write operations in DAM API AND DAM APP vs having a specialized (sub-)app for the cases where the external DAM does need write operations ?
• If the answer to the above is a resounding yes, then here are some additional thoughts/proposals for a WritableAssetProvider interface (all names just proposals as well)
  
  • AssetBuilder newAsset(Folder parent, String name).with(File/Stream/Path/URL).otherBuilderMethods(...).save();.Rationale here is a) we can't just pass any Asset instance (not all properties can be set arbitrarily) b) Asset provides an InputStream for the binary, but we'll presumably need a different input to "upload" it.
  • AssetModifier update(Asset assetToModify).changeFoo(String s).changeBar(..).save(); The rationale here is that a) not all readable properties can be modified (some are auto-generated, or inferred from the binary, for example) b) we need to keep track of what is getting changed
  • void move(Asset asset, Folder newParent);
  • void version(Asset, String label);
  • void delete(Asset asset);