There have been some discussion on creating an api package to create a simple way for people to interact and manipulate a gatein portal. Example situations would be things like creating a gadget, adding an application to a category, creating a page and adding it to a node, adding applications to a page, managing users, etc...

Two different solutions have been created, both are a bit different in approach. These are preliminary and are not meant to be complete, it is more meant to start of a discussion: https://github.com/metacosm/gatein-api

https://github.com/mwringe/gatein-api

Lets start a discussion on the above apis and what you would expect to come from an api like this.

_______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

> > First I want to reiterate that for the scope of next release we said we > stick with: > - application registry features > - page/navigation node metadata > So > - creating a page > - adding apps to a page > - managing users > is out of scope for the coming release. (will be for the release after)

> Some rough notes I took while looking into it, I mainly looked at the > testcases/usecases > > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > Looks like 2 first tests are contradicting themselves: > assert portal.getContentRegistry().getCategory("inexistent") == null; > assert portal.getContentRegistry().getCategory("inexistent") != null; Yes, I noticed that as well and this has already been addressed in the code. Note that I'm still debating wether getOrCreate methods are useful or not. They are useful for users who just want to retrieve something whether it previously existed or not. I'm not sure whether that's a predominant use case but I personally thought that it makes writing code against the API a little cleaner by avoiding a lot of boilerplate code. It also maps reasonably well to REST with the contract that GET will never fail (though I need to think this one through more) :) > ************ > public void assigningContentToAWindowOnAPage() > is out of scope of what we will provide in that version, we agreed to > have read-only info about pages/navigation nodes information without the > info about page compositions. I added this use case because this is actually something I need for WSRP (and I suspect Nick would need as well) import/export so I wanted to see how that particular scenario could work out.

> I was actually expecting something more like: > Portlet portlet = new Portlet(...); > Category category = new Category(...); > category.add(portlet); > contentRegistry.save(category); The less detached the API is, the better in my opinion. I would rather also have an API that is persistent by default, i.e. you don't need to do call save or update methods to persist the changes you made to "detached" entities. I understand, though, that it might be tricky to do so if we want to have large batches of modifications. I guess it boils down to whether we want the API to be mainly read-oriented or write-oriented or a mix of both. :)

> ************ > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > > getSingleResult in Hibernate isn't the best thing created, it actually > didn't make it through the JPA API. > I would rather remove this method from the API, and potentially add it > in some form later if really needed. > - Nodes.getSingleOrFail(Query.<Dashboard>builder().where(filter).build()); Yes, this is just syntactic sugar but an API is also a lot about syntactic sugar (making your users' life easier). However, it's probably a good idea to have a minimal version of the API first and then add the methods to smooth out the desire paths (http://en.wikipedia.org/wiki/Desire_path) once we've had some feedback on the API.

On May 25, 2011, at 10:35 AM, Boleslaw Dawidowicz wrote: > I need more time to give more detailed feedback but some quick comments inline. > > On May 25, 2011, at 9:44 AM, Christophe Laprun wrote: >>> >>> First I want to reiterate that for the scope of next release we said we >>> stick with: >>> - application registry features >>> - page/navigation node metadata >>> So >>> - creating a page >>> - adding apps to a page >>> - managing users >>> is out of scope for the coming release. (will be for the release after) > > For users if we drop the ID part of Chris proposal it can be decoupled from the API. Actually I would strongly argue to not complicate this part and leave user and group reference with simple string ("john" and "/platform/users"). You know my point of view on this… :) Again, the Id classes don't need to be as complex as they are in my current proposal. I just wanted to flesh out some generic Id ideas that I had to see if they were actually feasible. Plus, the complexity is not that high from a user perspective. Contrast: Groups.getGroup("/platform/users"); with: Groups.getGroup(Ids.getGroupId("platform", "users"));

for example. How does that complicate things? It is a little more complicated for us to implement but it's simpler for users because they don't need to know what the format of a group name is. They don't need to concatenate and/or parse Strings anytime they need to deal with a group name, etc. In the first version, you need to let users of the API know about the internal format of a group name and basically commit to it for a long time: it becomes an implicit part of the publish API. In the second case, you have a slight overhead of creating an intermediate object but one that you won't need to parse again. Most importantly, you never expose the internals of how groups are named, which makes it easier to evolve the internal implementation without impacting existing code. Also, the validation code goes into the Id creation and you can then assume in the getGroup method that the Id you get is actually valid which makes it easier to implement and not have to duplicate validation code all over the place. This also would help against things like XSS or injection attacks for example.

I would really like to hear a compelling argument against Ids as separate objects because so far, the only arguments I've heard are: I don't like them without any solid arguments as to why we shouldn't use them. Please enlighten me as I only see advantages to them! ;)

>>> Some rough notes I took while looking into it, I mainly looked at the >>> testcases/usecases >>> >>> https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... >>> Looks like 2 first tests are contradicting themselves: >>> assert portal.getContentRegistry().getCategory("inexistent") == null; >>> assert portal.getContentRegistry().getCategory("inexistent") != null; >> >> Yes, I noticed that as well and this has already been addressed in the code. Note that I'm still debating wether getOrCreate methods are useful or not. They are useful for users who just want to retrieve something whether it previously existed or not. I'm not sure whether that's a predominant use case but I personally thought that it makes writing code against the API a little cleaner by avoiding a lot of boilerplate code. It also maps reasonably well to REST with the contract that GET will never fail (though I need to think this one through more) :) >> >>> ************ >>> public void assigningContentToAWindowOnAPage() >>> is out of scope of what we will provide in that version, we agreed to >>> have read-only info about pages/navigation nodes information without the >>> info about page compositions. >> >> I added this use case because this is actually something I need for WSRP (and I suspect Nick would need as well) import/export so I wanted to see how that particular scenario could work out. >> > > Commenting on both getOrCreate() and assigningContentToAWindowOnAPage()... I know you and Nick may need it and I also understand that there may be good case for performance reasons. However we should place such dedicated or specialized method in internal API where it is fine but not in the public API. This is meant to be simple. Otherwise we'll end up with API bloated with lots and lots of methods like because of different needs. We should take our use cases into account but not to this level. Also I support the view that we should keep it simple and minimal - it is always possible to add and extend. Also it is easier to deprecate if we keep it simple getOrCreate actually doesn't make any sense on an internal API (well, at the implementation level, maybe) but it makes more sense at the user level to keep the code as simple as possible. Compare: Window window; if (!page.hasChild(windowName)) { window = page.createChild(windowName, Window.class); } else { window = page.getChild(windowName, Window.class); } with: Window window = page.getOrCreateChild(windowName, Window.class); when you only want to get a window with a given name and you don't care whether it's a new window or not, you just want a window with that name. I think this use case makes sense when assembling a portal from scratch and you just want to get it done in as little code as possible. Imagine having to create lots of pages and assigning content to it and you'll get bored quickly of the check then create or get boilerplate code… :) Then it's a matter of which use cases we want to make easier for people. I agree that the API should probably be as simple as possible first so that usage patterns can develop and then we can improve things but even in my tiny use cases I got bored of the boilerplate code quickly so I can envision users doing the same :) On assigning content to a window, this is something that is needed by users as well: how else do you tell the portal that you want such and such content to be displayed on a given page? This last one as nothing to do with performance. Regardless of how you do it, users will need to be able to tell the API: I want this portlet displayed here on this page. Whether this is something we want the API to do in the first iteration or not is a different issue. So +1 to remove it from the fist iteration, but -100 to tell me to remove it because it's only a convenience method for Nick or I. :) >>> >>> I was actually expecting something more like: >>> Portlet portlet = new Portlet(...); >>> Category category = new Category(...); >>> category.add(portlet); >>> contentRegistry.save(category); >> >> The less detached the API is, the better in my opinion. I would rather also have an API that is persistent by default, i.e. you don't need to do call save or update methods to persist the changes you made to "detached" entities. I understand, though, that it might be tricky to do so if we want to have large batches of modifications. I guess it boils down to whether we want the API to be mainly read-oriented or write-oriented or a mix of both. :) >> > > IMO having such state aware entities instead of POJOs will be opening another can of worms (to use your own words ;). Think about user persisting those objects somewhere, or have them flying between cluster instances and having some variation of infamous LazyInitializationException. Obviously it can be done and properly solved but will add unnecessary complexity. I think you misunderstood what I meant. The term detached refers to the situation you describe where you create objects, you deal with them then persist them (and you have to remember to do so). Users shouldn't need to persist objects elsewhere than in the GateIn "database". Maintaining consistency across cluster instances is a lot easier if all modifications to objects are persistent (i.e. the database is always up to date, though obviously pushing updates to the different instances is always a tricky issue). The persisting service(s) needed by the objects to save themselves should be injected via something like CDI. Even without having persistent method calls, I don't think that users should create new instances of objects directly and then save them. They should ask the API services for an instance and then act on it. This way, this instance is always managed by GateIn and we don't have completely detached objects. tl;dr: +1 on adding save and update methods if needed (though I would try to avoid them as much as possible), -1 on letting users create completely detached objects. >>> ************ >>> https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... >>> >>> getSingleResult in Hibernate isn't the best thing created, it actually >>> didn't make it through the JPA API. >>> I would rather remove this method from the API, and potentially add it >>> in some form later if really needed. >>> - Nodes.getSingleOrFail(Query.<Dashboard>builder().where(filter).build()); >> >> Yes, this is just syntactic sugar but an API is also a lot about syntactic sugar (making your users' life easier). However, it's probably a good idea to have a minimal version of the API first and then add the methods to smooth out the desire paths (http://en.wikipedia.org/wiki/Desire_path) once we've had some feedback on the API. > > Yes, +1 on keeping it minimal approach. We can always add more sophisticated methods to internal APIs > > Bolek Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

On May 25, 2011, at 4:34 PM, Matt Wringe wrote: > On Wed, 2011-05-25 at 12:07 +0200, Christophe Laprun wrote: >> On May 25, 2011, at 10:35 AM, Boleslaw Dawidowicz wrote: >> >>> I need more time to give more detailed feedback but some quick comments inline. >>> >>> On May 25, 2011, at 9:44 AM, Christophe Laprun wrote: >>>>> >>>>> First I want to reiterate that for the scope of next release we said we >>>>> stick with: >>>>> - application registry features >>>>> - page/navigation node metadata >>>>> So >>>>> - creating a page >>>>> - adding apps to a page >>>>> - managing users >>>>> is out of scope for the coming release. (will be for the release after) >>> >>> For users if we drop the ID part of Chris proposal it can be decoupled from the API. Actually I would strongly argue to not complicate this part and leave user and group reference with simple string ("john" and "/platform/users"). >> >> You know my point of view on this… :) >> Again, the Id classes don't need to be as complex as they are in my >> current proposal. I just wanted to flesh out some generic Id ideas >> that I had to see if they were actually feasible. >> >> Plus, the complexity is not that high from a user perspective. >> Contrast: >> Groups.getGroup("/platform/users"); >> with: >> Groups.getGroup(Ids.getGroupId("platform", "users")); > > but what about Groups.getGroup("platform", "users");? Would work for this particular use case… but see below. > I don't know if we really need to have a separate complex id system. The > id system should just be doing the parsing anyways and passing that on > to the portal. Id system? Again, it doesn't need to be complex, it only needs to be encapsulated. >> for example. How does that complicate things? It is a little more >> complicated for us to implement but it's simpler for users because >> they don't need to know what the format of a group name is. They don't >> need to concatenate and/or parse Strings anytime they need to deal >> with a group name, etc. >> >> In the first version, you need to let users of the API know about the >> internal format of a group name and basically commit to it for a long >> time: it becomes an implicit part of the publish API. In the second >> case, you have a slight overhead of creating an intermediate object >> but one that you won't need to parse again. Most importantly, you >> never expose the internals of how groups are named, which makes it >> easier to evolve the internal implementation without impacting >> existing code. Also, the validation code goes into the Id creation and >> you can then assume in the getGroup method that the Id you get is >> actually valid which makes it easier to implement and not have to >> duplicate validation code all over the place. This also would help >> against things like XSS or injection attacks for example. > > Shouldn't the actual components be checking that the identifiers passed > to them are correct? I don't know if we want to have a complex id > verification system in the api. The verification process should be done > in only one location. I meant checking the format. If you have several methods that take Strings id as parameters, each method will first need to call some validation of the format first. Checking that the id actually maps to a valid component is then up to the backend, not the component itself. > Things like XSS may need to be dealt with in the api. Not sure what you mean here that is different from what I said :) >> I would really like to hear a compelling argument against Ids as >> separate objects because so far, the only arguments I've heard are: I >> don't like them without any solid arguments as to why we shouldn't use >> them. Please enlighten me as I only see advantages to them! ;) > > I don't know why they are really needed since: > > getElement(ID.createElementID("element1", "elementTypeA")) > > can be handled more simply with: > > getElement("element1", "elementTypeA"); Except that Ids don't have all the same formats so that prevents generic methods. For example, you couldn't have ContentRegistry.getContent("warName", "portletName") because that would conflict with ContentRegistry.getContent("invokerName", "portletHandle") for the WSRP case.

Bypassing the Id object would only work in non-ambiguous cases and I'm fine with doing so.

However, there are cases where it wouldn't work. Also, again, it would mean that each method that needs to work with an identifier would need to first perform the intermediate step (though obviously that code could be mutualized internally, but if we're going this step, why not have Ids? ^_^).

Plus, T getElement(Id<T> id) would allow us to have typesafety at the id and returned value level, something you wouldn't be able to do with getElement(String... ).

This is a valid point. However, it's still not a very strong argument against Id as separate objects. What is the big issue in your opinion with having separate Id objects?

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

On May 25, 2011, at 6:06 PM, Matt Wringe wrote: >>> Except that Ids don't have all the same formats so that prevents >> generic methods. For example, you couldn't have >> ContentRegistry.getContent("warName", "portletName") because that >> would conflict with ContentRegistry.getContent("invokerName", >> "portletHandle") for the WSRP case. > > But that is just an implementation detail. The devil is in the (implementation) details… :) > applicationRegistry.getPortletRepository(LOCAL).getPortlet("warName", > "portletName"); > applicationRegistry.getPortletRepository(wsrp.SELF).getPortlet("portletHandle"); Except that getPortlet(String, String) wouldn't make any sense on a local PortletRepository and the getPortlet(String) version wouldn't make any sense on the remote version.

> [well, I guess if wsrp uses portletHandles, I need to relook at how my > portlet repository class currently works] One of the point of using Ids is that the same method works in all the different contexts. So you don't need subclasses for specific cases, you might just need (if at all) different implementations of the same interface. >> Bypassing the Id object would only work in non-ambiguous cases and >> I'm fine with doing so. > > We can always write the api so its going to be non-ambiguous with > respect to this. By making special cases all over the place, yes. Which is what I'm trying to avoid. Keeping the API coherent and consistent, avoiding special cases for different content types.

> >> However, there are cases where it wouldn't work. Also, again, it >> would mean that each method that needs to work with an identifier >> would need to first perform the intermediate step (though obviously >> that code could be mutualized internally, but if we're going this >> step, why not have Ids? ^_^). > >> Plus, T getElement(Id<T> id) would allow us to have typesafety at the >> id and returned value level, something you wouldn't be able to do with >> getElement(String... ). > >> This is a valid point. However, it's still not a very strong argument >> against Id as separate objects. What is the big issue in your opinion >> with having separate Id objects? > > Its cumbersome to always have to think and create ids to do something, > when it can be done more directly without them. Its also confusing if > some elements require these ids while others don't (ie a category > doesn't need a separate id class, since it can be differentiated by a > string). > > I don't think it makes sense to have things like > > Id id = Id.generateId("foo", "bar"); > Element element = something.getElement(id); > > instead of just: > Element element = something.getElement("foo", "bar"); because you're assuming that getElement will always be able to construct an unambiguous identifier given 2 strings, which as I've shown already doesn't work with WSRP. > Ok, so lets say we need to have more complex ids: > > PortletId pId = Id.generatePortletID("foo", "bar"); > WSRPId wId = Id.generateWSRPPortletId("foo", "bar"); > GadgetId gId = Id.generateGadgetID("foo", "bar"); > > Portlet portlet = getApplication(pId); > Portlet portlet = getApplication(wId); > Gadget gadget = getApplication(gId); > > We can still handle it using something like: > > getApplication(Application.Portlet, "foo", "bar"); > getApplication(Application.WSRP, "foo", "bar"); > getApplication(Application.Gadget, "foo", "bar"); That last one could be a solution but it's not any cleaner than getApplication(Id<Portlet> id) which will also have the benefits of allowing us to do: Portlet portlet = getApplication(Id<Portlet> id) which your other solutions (apart from enumerating all possible cases) don't. > but in this case I would argue that we use getPortlet("foo", "bar") and > getGadget("foo","bar"). But for the wsrp case, its get a bit more tricky > (which is why I have multiple portlet repository classes). Well, WSRP needs to be treated as a first class citizen. And we need to make an API that would also accommodate other kinds of content without to have to change it and make new special cases. Enumerating over the known cases at a given point won't give us a very future-proof API and lead into issues where code will make assumptions that new content types we might support might not follow. I understand that we shouldn't try to plan for every possible scenarios under the sun but with what we currently have the String as Id approach is already showing limits when encapsulating identifiers in a separate object wouldn't cost much and lead to easier evolution of the API if needed. Another (and probably last) thing I will say in favor of encapsulating identifiers in a separate object is that it makes it more natural to use artificial identifiers (think SSN) instead of natural ones (think last name).

Using artificial identifiers has lots of benefits, one of which being stability in the face of renames, which is an important property for a REST API (you don't want your URIs to change just because you've renamed an entity to something else). It also allows objects to be identified via other things than a name if needed (get a user id based on an OAuth token for example) and the API won't change since it will still deal with the Id class instead of needing to add yet another version of the get methods to accommodate the new modality. Obviously, that's not necessarily something we want/need to support but considering that the cost of using Ids instead of Strings is pretty low, I have yet to see a really compelling argument not to. And with this, I won't argue about the value of having separate Ids anymore. I think I've made my point. I agree that using Strings looks simpler but I worry that it might actually make implementing the API more complex and less future-proof when the cost of using separate Ids seems pretty low.

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

On May 25, 2011, at 8:11 AM, Thomas Heute wrote: > > Thanks for sharing this Matt, see inline > > On 05/25/2011 05:08 AM, Matt Wringe wrote: >> There have been some discussion on creating an api package to create a >> simple way for people to interact and manipulate a gatein portal. >> >> Example situations would be things like creating a gadget, adding an >> application to a category, creating a page and adding it to a node, >> adding applications to a page, managing users, etc... > > First I want to reiterate that for the scope of next release we said we > stick with: > - application registry features > - page/navigation node metadata > So > - creating a page > - adding apps to a page > - managing users > is out of scope for the coming release. (will be for the release after) > >> Two different solutions have been created, both are a bit different in >> approach. These are preliminary and are not meant to be complete, it is >> more meant to start of a discussion: >> >> https://github.com/metacosm/gatein-api > > Some rough notes I took while looking into it, I mainly looked at the > testcases/usecases > > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > Looks like 2 first tests are contradicting themselves: > assert portal.getContentRegistry().getCategory("inexistent") == null; > assert portal.getContentRegistry().getCategory("inexistent") != null; Yes, I noticed that as well and this has already been addressed in the code. Note that I'm still debating wether getOrCreate methods are useful or not. They are useful for users who just want to retrieve something whether it previously existed or not. I'm not sure whether that's a predominant use case but I personally thought that it makes writing code against the API a little cleaner by avoiding a lot of boilerplate code. It also maps reasonably well to REST with the contract that GET will never fail (though I need to think this one through more) :)

> ************ > public void assigningContentToAWindowOnAPage() > is out of scope of what we will provide in that version, we agreed to > have read-only info about pages/navigation nodes information without the > info about page compositions. I added this use case because this is actually something I need for WSRP (and I suspect Nick would need as well) import/export so I wanted to see how that particular scenario could work out.

> ************ > public void assigningContentToACategory() > > registry.getOrCreateCategory("category"); > I prefer getCategory() and createCategory() to be distinct (with proper > exceptions), plus if there is a need for a getOrCreate or > getCategory(String name, boolen create) we can add it later Like I said, I'm still debating the usefulness of such methods. You'll see that some use cases use the check-for-existence/create or get pattern whether others use getOrCreate directly. It's true that we can add the getOrCreate methods later if needed.

> category.getKnownManagedContentIds(); > Meaning ? Confused about the testcase. What's a ManagedContent ? Basically Content is read-only: portlet, remote portlet, gadget, etc. When you add it to a category, it becomes managed and some of its properties can then be modified (display name, title, etc). Basically, you need something that is a wrapper around the read-only content as a portlet can be added to different categories with different names (and presumably at some point, different preferences though it's not currently available via the application registry). I first had implemented a version that didn't require ManagedContent but then it made using Content a lot more complex because you would need to change the reference you held to a given Content after you added it to a category to be able to manipulate it. Basically, I previously had: Application addedApp = category.add(application); assert category.contains(name); assert addedApp.equals(category.getApplication(name)); assert addedApp.isManaged(); assert !application.equals(category.getApplication(name)) : "The added application should be wrapped so that it can be modified"; assert application.equals(addedApp.getDeployedParent());

List<Application> applications = registry.getManagedApplications(Filter.ALL, Filter.ALL, Application.SORT_BY_NAME); assert applications.size() == 1 : "There should only be one application matching"; assert applications.contains(addedApp) : "Application should have become managed"; assert !applications.contains(application) : "Original application should have been left untouched"; try { application.setDisplayName("displayName"); Assert.fail("Shouldn't be possible to modify the original application. Use the result of Category.add instead."); } catch (ApplicationException e) { // expected } See: https://github.com/metacosm/gatein-api/blob/5df7e9a7feacb13ad2198414b540f... for the full version. So things were a lot trickier to deal with and I decided to make the concept explicit rather than implicit.

Matt's version deals with this the same way I used to: //NOTE: the returned application is _not_ the same object as the one passed. The returned application // should be mostly a clone of the passed application (but maybe slightly different, eg the name passed may change something like the display-name). public Application addApplication(String name, Application application);

but that opens a can of worms in my opinion as users might not understand why they need to change the reference to their application to be able to use it so I decided against transparent wrapping and in favor of explicit one. Even though it makes for a slightly more complex API at first glance, I believe it's actually easier to deal with > I was actually expecting something more like: > Portlet portlet = new Portlet(...); > Category category = new Category(...); > category.add(portlet); > contentRegistry.save(category); The less detached the API is, the better in my opinion. I would rather also have an API that is persistent by default, i.e. you don't need to do call save or update methods to persist the changes you made to "detached" entities. I understand, though, that it might be tricky to do so if we want to have large batches of modifications. I guess it boils down to whether we want the API to be mainly read-oriented or write-oriented or a mix of both. :)

> ************ > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > > getSingleResult in Hibernate isn't the best thing created, it actually > didn't make it through the JPA API. > I would rather remove this method from the API, and potentially add it > in some form later if really needed. > - Nodes.getSingleOrFail(Query.<Dashboard>builder().where(filter).build()); Yes, this is just syntactic sugar but an API is also a lot about syntactic sugar (making your users' life easier). However, it's probably a good idea to have a minimal version of the API first and then add the methods to smooth out the desire paths (http://en.wikipedia.org/wiki/Desire_path) once we've had some feedback on the API.

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

On Wed, 2011-05-25 at 09:44 +0200, Christophe Laprun wrote: > On May 25, 2011, at 8:11 AM, Thomas Heute wrote: > > > > > Thanks for sharing this Matt, see inline > > > > On 05/25/2011 05:08 AM, Matt Wringe wrote: > >> There have been some discussion on creating an api package to create a > >> simple way for people to interact and manipulate a gatein portal. > >> > >> Example situations would be things like creating a gadget, adding an > >> application to a category, creating a page and adding it to a node, > >> adding applications to a page, managing users, etc... > > > > First I want to reiterate that for the scope of next release we said we > > stick with: > > - application registry features > > - page/navigation node metadata > > So > > - creating a page > > - adding apps to a page > > - managing users > > is out of scope for the coming release. (will be for the release after) yes, so we don't need to include this as part of the first implementation, but since its something we want to do in future versions, its good to have an idea about how it could all work together. > >> Two different solutions have been created, both are a bit different in > >> approach. These are preliminary and are not meant to be complete, it is > >> more meant to start of a discussion: > >> > >> https://github.com/metacosm/gatein-api > > > > Some rough notes I took while looking into it, I mainly looked at the > > testcases/usecases > > > > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > > Looks like 2 first tests are contradicting themselves: > > assert portal.getContentRegistry().getCategory("inexistent") == null; > > assert portal.getContentRegistry().getCategory("inexistent") != null; > > Yes, I noticed that as well and this has already been addressed in the code. Note that I'm still debating wether getOrCreate methods are useful or not. They are useful for users who just want to retrieve something whether it previously existed or not. I'm not sure whether that's a predominant use case but I personally thought that it makes writing code against the API a little cleaner by avoiding a lot of boilerplate code. It also maps reasonably well to REST with the contract that GET will never fail (though I need to think this one through more) :) > > > ************ > > public void assigningContentToAWindowOnAPage() > > is out of scope of what we will provide in that version, we agreed to > > have read-only info about pages/navigation nodes information without the > > info about page compositions. > > I added this use case because this is actually something I need for WSRP (and I suspect Nick would need as well) import/export so I wanted to see how that particular scenario could work out. > > > ************ > > public void assigningContentToACategory() > > > > registry.getOrCreateCategory("category"); > > I prefer getCategory() and createCategory() to be distinct (with proper > > exceptions), plus if there is a need for a getOrCreate or > > getCategory(String name, boolen create) we can add it later > > Like I said, I'm still debating the usefulness of such methods. You'll see that some use cases use the check-for-existence/create or get pattern whether others use getOrCreate directly. It's true that we can add the getOrCreate methods later if needed. > > > category.getKnownManagedContentIds(); > > Meaning ? Confused about the testcase. What's a ManagedContent ? > > Basically Content is read-only: portlet, remote portlet, gadget, etc. When you add it to a category, it becomes managed and some of its properties can then be modified (display name, title, etc). Basically, you need something that is a wrapper around the read-only content as a portlet can be added to different categories with different names (and presumably at some point, different preferences though it's not currently available via the application registry). I first had implemented a version that didn't require ManagedContent but then it made using Content a lot more complex because you would need to change the reference you held to a given Content after you added it to a category to be able to manipulate it. > > Basically, I previously had: > Application addedApp = category.add(application); > assert category.contains(name); > assert addedApp.equals(category.getApplication(name)); > assert addedApp.isManaged(); > assert !application.equals(category.getApplication(name)) : "The added application should be wrapped so that it can be modified"; > assert application.equals(addedApp.getDeployedParent()); > > List<Application> applications = registry.getManagedApplications(Filter.ALL, Filter.ALL, Application.SORT_BY_NAME); > assert applications.size() == 1 : "There should only be one application matching"; > assert applications.contains(addedApp) : "Application should have become managed"; > assert !applications.contains(application) : "Original application should have been left untouched"; > > try > { > application.setDisplayName("displayName"); > Assert.fail("Shouldn't be possible to modify the original application. Use the result of Category.add instead."); > } > catch (ApplicationException e) > { > // expected > } > > See: https://github.com/metacosm/gatein-api/blob/5df7e9a7feacb13ad2198414b540f... for the full version. > > So things were a lot trickier to deal with and I decided to make the concept explicit rather than implicit. > > Matt's version deals with this the same way I used to: > > //NOTE: the returned application is _not_ the same object as the one > passed. The returned application > // should be mostly a clone of the passed application (but maybe > slightly different, eg the name passed may change something like the > display-name). > public Application addApplication(String name, Application > application); > > but that opens a can of worms in my opinion as users might not > understand why they need to change the reference to their application > to be able to use it so I decided against transparent wrapping and in > favor of explicit one. yes, I agree, its not a great solution with the current implementation. The idea here was that an application type object would use the same object class in the 'repository', in a category and on a page. When you would add an application from the repository to the category, it would inherit all the repositories properties, but they could also be overwritten and customized. The idea would be the same for when you place an application from a category onto a page. We could also handle things like security permissions, where a parent application security permissions always takes precedent. But the current implementation is not going to really work nicely with this. With the current implementation, many of the application properties don't exist from the repository version.

> Even though it makes for a slightly more complex API at first glance, > I believe it's actually easier to deal with because things are > explicit and you keep the original content read-only. So how do you handle adding an application from a category to a page? Doesn't this have to create a new object with the same properties? Or do you have repository applications, category applications and page applications? > > I was actually expecting something more like: > > Portlet portlet = new Portlet(...); > > Category category = new Category(...); > > category.add(portlet); > > contentRegistry.save(category); > > The less detached the API is, the better in my opinion. I would rather > also have an API that is persistent by default, i.e. you don't need to > do call save or update methods to persist the changes you made to > "detached" entities. I understand, though, that it might be tricky to > do so if we want to have large batches of modifications. I guess it > boils down to whether we want the API to be mainly read-oriented or > write-oriented or a mix of both. :) I don't know if it makes sense to create the object separately if the object should only exist as an element of another class. > > ************ > > https://github.com/metacosm/gatein-api/blob/master/src/test/java/org/gate... > > > > getSingleResult in Hibernate isn't the best thing created, it actually > > didn't make it through the JPA API. > > I would rather remove this method from the API, and potentially add it > > in some form later if really needed. > > - Nodes.getSingleOrFail(Query.<Dashboard>builder().where(filter).build()); > > Yes, this is just syntactic sugar but an API is also a lot about syntactic sugar (making your users' life easier). However, it's probably a good idea to have a minimal version of the API first and then add the methods to smooth out the desire paths (http://en.wikipedia.org/wiki/Desire_path) once we've had some feedback on the API. > > Cordialement / Best, > Chris > > == > Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. > Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein > Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm > _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

There have been some discussion on creating an api package to create a simple way for people to interact and manipulate a gatein portal. Example situations would be things like creating a gadget, adding an application to a category, creating a page and adding it to a node, adding applications to a page, managing users, etc... Two different solutions have been created, both are a bit different in approach. These are preliminary and are not meant to be complete, it is more meant to start of a discussion: https://github.com/metacosm/gatein-api https://github.com/mwringe/gatein-api Lets start a discussion on the above apis and what you would expect to come from an api like this. _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

Some comments on Matt's work in no particular order. The use cases developed in the test cases are pretty simple so it's difficult to get a good feel for the API when trying to accomplish things that are more complex.

GateIn.getPortal() won't quite work as there can be several portal containers and each of these can in turn contain several portals so we need to be able to identify which Portal we want to work with precisely.

I'm not too sure about GadgetRepository and PortletRepository. I see why you have them but I'd rather have only one repository for all possible content first if possible. It is true that I somewhat neglected the Gadget case so I will do that now. :)

I think it's best to return Iterable instead of Iterator for collections. I use a subclass of Iterable that augment the base interface with size and contains methods as both methods could be implemented without needing to load the entire collection in memory. Even without the additional methods, Iterable is better because it allows to write code such as: Iterable<Item> items; for(Item item : items) { // actual code } As discussed in a previous email, the fact that you use the same class to represent "original" content (i.e. one that comes directly from your repositories and which should be as read-only as possible) and what I call managed (or customized for Thomas) content (i.e. one that has been added to a category) can create a confusion for users as to which version is which and why some Applications can be modified and other not. I initially chose to implement this the same way you did before deciding to make it more explicit. Of course, I don't like nodeManager.getNode("/home/testA/testB/testC") :) Apart from the fact that it hardcodes the internals of node naming in the client code,

it also means that you cannot retrieve a node without first retrieving its parent portal, then its NodeManager, etc. I'm still wondering if it's a good thing or not :) Why not put the node methods directly on Portal instead of having a separate NodeManager? The same actually goes for PageManager since they need a parent portal to work correctly i.e. what they return is scoped only to the parent Portal (since "/home/testA/testB/testC" is not a valid node id over the whole set of existing nodes for a complete GateIn install)

. The advantage of your solution (as opposed to mine, which has a Nodes classes to query all nodes across all portal containers / portals)

is that it is easier to get away with using Strings to identify nodes as opposed to having to deal with complex ids like "portal#classic:/web/NavigationPortlet"… On Query, I prefer to use my version that is built fluently (which seems to be the predominant idiom for such use case at the moment in APIs, see http://relation.to/Bloggers/ATypesafeCriteriaQueryAPIForJPA for example) and is a little more typesafe but I guess that's a matter of preference.

That's it for now, I would really like to see more fleshed out use cases to be able to get a better feel for the API. :)

On May 25, 2011, at 5:08 AM, Matt Wringe wrote: > There have been some discussion on creating an api package to create a > simple way for people to interact and manipulate a gatein portal. > > Example situations would be things like creating a gadget, adding an > application to a category, creating a page and adding it to a node, > adding applications to a page, managing users, etc... > > Two different solutions have been created, both are a bit different in > approach. These are preliminary and are not meant to be complete, it is > more meant to start of a discussion: > > https://github.com/metacosm/gatein-api > https://github.com/mwringe/gatein-api > > Lets start a discussion on the above apis and what you would expect to > come from an api like this. > > _______________________________________________ > gatein-dev mailing list > gatein-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/gatein-dev Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

Hi, I spent a bit of time reviewing this and the immediate feedback I can do is: 1/ I see improvement in Chris work about the ID part and I think the Id<T> is quite good with the factory method that make them intuitive to create. However on the stylistic view my opinion is that it would make sense to avoid the "get" style like getUserId and simply have "userId" because static import allows to write: User root = Users.get(userId("root")); instead of: Id<User> id = Ids.getUserId("root"); User root = Users.get(id); 2/ There are two parts which are out of scope of the current API that we should remove which are the portal container and the UI component. The current API should not mention the portal container and every work should be scoped to the current portal container. This notion exist for isolating deployments (for instance one portal container per customer). I think Matt has this right so far but not Chris API that mentions it. The UI component part is not part of the scope of the current API and we should leave it aside and address it later. However we still need the Page notion but as a way to find pages (not create them because we don't address for now the UI component part). Mostly pages will be associated with navigations programmatically. I will do further comments after the point 2/ is addressed (it should unclutter a bit the API). On May 25, 2011, at 5:08 AM, Matt Wringe wrote: > There have been some discussion on creating an api package to create a > simple way for people to interact and manipulate a gatein portal. > > Example situations would be things like creating a gadget, adding an > application to a category, creating a page and adding it to a node, > adding applications to a page, managing users, etc... > > Two different solutions have been created, both are a bit different in > approach. These are preliminary and are not meant to be complete, it is > more meant to start of a discussion: > > https://github.com/metacosm/gatein-api > https://github.com/mwringe/gatein-api > > Lets start a discussion on the above apis and what you would expect to > come from an api like this. > > _______________________________________________ > gatein-dev mailing list > gatein-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/gatein-dev _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

On May 31, 2011, at 10:54 AM, Boleslaw Dawidowicz wrote: > Additionally Organization is out of scope of current API work as well. We don't have time to address it properly and minimal inclusion of new interfaces can limit us in the future. Therefor we should stick for now with just references like "root", "gtn" or "/platform/users" So, to be clear, you want me to remove the whole organization package, correct?

> 2/ There are two parts which are out of scope of the current API that we should remove which are the portal container and the UI component. > > The current API should not mention the portal container and every work should be scoped to the current portal container. This notion exist for isolating deployments (for instance one portal container per customer). I think Matt has this right so far but not Chris API that mentions it. OK. I took the point of view that the API needed to be able to create portal containers and portals and I indeed didn't scope the objects to the current portal. I will change that.

you are confusing portal container and portal entity. a portal container has multiple portals, see DataStorage#getPortalConfig(String) a portal container contains a set of services related to multiple sites (portal/group/user).

Matt did something simple that was solving the case.

On Jun 10, 2011, at 2:01 PM, Julien Viet wrote: > Matt did something simple that was solving the case. Unless I am mistaken, and Matt can prove me wrong on this, Matt didn't address this use case. Everything in Matt's version is scoped to the current portal, not portal container. Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

indeed this is correct it should be done with a getPortal(String name) / Collection<Portal> getPortals() from your entry point of the API (something like GateIn object of Matt).

Basically what we aim to do is an API that expose this data structure: <764a37d6.png>

On Jun 10, 2011, at 3:33 PM, Julien Viet wrote: > indeed this is correct it should be done with a getPortal(String name) / Collection<Portal> getPortals() from your entry point of the API (something like GateIn object of Matt). I used to have something like that as well, except that it was used to retrieved the PortalContainers as well, so you could navigate everything. > Basically what we aim to do is an API that expose this data structure: > > <764a37d6.png> What did you use to create the diagram? Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

I've pushed some changes to github.com/metacosm/gatein-api. I will re-work completely the navigation use cases based on the recent exchanges when I come back from vacations. I guess the current scope of the API is not as extended as I first thought so there are lots of things that will disappear from the current design. On Jun 10, 2011, at 5:21 PM, Julien Viet wrote: > here is an updated version with the notion of site : > > <5806d87d.png> > On Jun 10, 2011, at 4:47 PM, Christophe Laprun wrote: > >> >> On Jun 10, 2011, at 3:33 PM, Julien Viet wrote: >> >>> indeed this is correct it should be done with a getPortal(String name) / Collection<Portal> getPortals() from your entry point of the API (something like GateIn object of Matt). >> >> I used to have something like that as well, except that it was used to retrieved the PortalContainers as well, so you could navigate everything. >> >>> Basically what we aim to do is an API that expose this data structure: >>> >>> <764a37d6.png> >> >> What did you use to create the diagram? >> >> Cordialement / Best, >> Chris >> >> == >> Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. >> Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein >> Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm >> > Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

1/ the content registry is not tied to a particular portal but instead is the same for any site (including group/user) so it should be available on the GateIn interface

2/ I don't get the difference between Portal (which extends Node) and Site (which extends Navigation). A site is a container for pages and navigations. A portal extends a site (as it provides more things). 3/ what does the Node interface describe ? I don't see a real interest in there and it makes things more complex to understand, specially with the generics public interface Navigation<T extends Node<T>> extends GateInObject<Navigation>, Container<Navigation> I think we can afford to use generics, but we cannot afford to use too many generics. On Jun 28, 2011, at 5:42 PM, Christophe Laprun wrote: > I've pushed the navigation changes to http://github.com/metacosm/gatein-api along with other changes. Please let me know what you think! > > On Jun 10, 2011, at 11:20 PM, Christophe Laprun wrote: > >> I've pushed some changes to github.com/metacosm/gatein-api. I will re-work completely the navigation use cases based on the recent exchanges when I come back from vacations. I guess the current scope of the API is not as extended as I first thought so there are lots of things that will disappear from the current design. >> >> On Jun 10, 2011, at 5:21 PM, Julien Viet wrote: >> >>> here is an updated version with the notion of site : >>> >>> <5806d87d.png> >>> On Jun 10, 2011, at 4:47 PM, Christophe Laprun wrote: >>> >>>> >>>> On Jun 10, 2011, at 3:33 PM, Julien Viet wrote: >>>> >>>>> indeed this is correct it should be done with a getPortal(String name) / Collection<Portal> getPortals() from your entry point of the API (something like GateIn object of Matt). >>>> >>>> I used to have something like that as well, except that it was used to retrieved the PortalContainers as well, so you could navigate everything. >>>> >>>>> Basically what we aim to do is an API that expose this data structure: >>>>> >>>>> <764a37d6.png> >>>> >>>> What did you use to create the diagram? >>>> >>>> Cordialement / Best, >>>> Chris >>>> >>>> == >>>> Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. >>>> Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein >>>> Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm >>>> >>> >> >> Cordialement / Best, >> Chris >> >> == >> Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. >> Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein >> Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm >> >> >> _______________________________________________ >> gatein-dev mailing list >> gatein-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/gatein-dev > > Cordialement / Best, > Chris > > == > Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. > Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein > Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm > > > _______________________________________________ > gatein-dev mailing list > gatein-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/gatein-dev _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

1/ the content registry is not tied to a particular portal but instead is the same for any site (including group/user) so it should be available on the GateIn interface

2/ I don't get the difference between Portal (which extends Node) and Site (which extends Navigation). A site is a container for pages and navigations. A portal extends a site (as it provides more things). 3/ what does the Node interface describe ? I don't see a real interest in there and it makes things more complex to understand, specially with the generics

public interface Navigation<T extends Node<T>> extends GateInObject<Navigation>, Container<Navigation> I think we can afford to use generics, but we cannot afford to use too many generics.

only Page should extends Targetable. why do we have Portal and Navigation also extending it ?

I don't understand : Navigation sub = nav.getChild("sub"); Navigation navigation = portal.createNavigationTo(sub, portal.getNavigation()); in creatingANavigationShouldLinkNavigationAndNode() method

On Jul 7, 2011, at 12:42 PM, Christophe Laprun wrote: > > On Jul 7, 2011, at 12:11 PM, Julien Viet wrote: > >> I don't understand : >> >> Navigation sub = nav.getChild("sub"); >> Navigation navigation = portal.createNavigationTo(sub, portal.getNavigation()); >> >> in creatingANavigationShouldLinkNavigationAndNode() method > > It basically creates a new Navigation pointing to the existing sub navigation, using the root navigation of the portal as parent. > I can remove Targetable altogether if needed. Looking at it some more, it really didn't make sense. I've removed Targetable from Navigation and Portal and fixed the test accordingly. Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm _______________________________________________ gatein-dev mailing list gatein-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/gatein-dev

On Jul 8, 2011, at 10:35 AM, Julien Viet wrote: > several remarks at first sight: > > 1/ one thing that was discussed on PL (Project Lead) conf call last time was to have a typed version of the target on the navigation: > > Page getPageTarget(); > void setPageTarget(Page page); > as 97% of the time, the target of a navigation will be a Page (most importantly now as we have no other possible target). I'm not part of PL so I wouldn't know that. It's been mentioned but I didn't see the harm of having something more generic since we know it's probably going to be extended. > 2/ I would like to have the Container interface no use the term "child" as that would make it more reusable (item or element instead) OK. > 3/ a site should not be a Container<Page> for several reasons > - pragmatic : a site can have a large number pages (2000) in some case and the default method to get children of Container#getChildren() would drain the resource of the server This can me mediated by having automatically paged IterableResults.

> - conceptual : a site is a container of pages and navigations and in the future it could contain other things (like web resource for instance) Makes sense. Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm

On Jul 7, 2011, at 11:25 AM, Julien Viet wrote: > only Page should extends Targetable. > > why do we have Portal and Navigation also extending it ? For Portal: it's there so you could create Navigations automatically from a Portal instead of having to create the whole tree by hand. For Navigation: so that you could reuse a navigation subtree elsewhere. See NavigationTestCase for some use cases.

From what I understood only Page should be a target in Navigation.setTarget() right?

On May 31, 2011, at 10:47 AM, Julien Viet wrote: > I spent a bit of time reviewing this and the immediate feedback I can do is: > > 1/ I see improvement in Chris work about the ID part and I think the Id<T> is quite good with the factory method that make them intuitive to create. > > However on the stylistic view my opinion is that it would make sense to avoid the "get" style like getUserId and simply have "userId" because static import allows to write: > > User root = Users.get(userId("root")); > > instead of: > > Id<User> id = Ids.getUserId("root"); > User root = Users.get(id); Done. > 2/ There are two parts which are out of scope of the current API that we should remove which are the portal container and the UI component. > > The current API should not mention the portal container and every work should be scoped to the current portal container. This notion exist for isolating deployments (for instance one portal container per customer). I think Matt has this right so far but not Chris API that mentions it. OK. I took the point of view that the API needed to be able to create portal containers and portals and I indeed didn't scope the objects to the current portal. I will change that. > The UI component part is not part of the scope of the current API and we should leave it aside and address it later. However we still need the Page notion but as a way to find pages (not create them because we don't address for now the UI component part). Mostly pages will be associated with navigations programmatically. I'm not too sure what you mean here.

Cordialement / Best, Chris == Principal Software Engineer / JBoss Enterprise Middleware Red Hat, Inc. Follow GateIn: http://blog.gatein.org / http://twitter.com/gatein Follow me: http://metacosm.info/metacosm / http://twitter.com/metacosm