Now don’t get me wrong, I like gigaspaces and I am not into bashing someones API for the sake of it. Take a look at the GigaSpace interface documented in javadoc: http://www.gigaspaces.com/docs/JavaDoc7.1/org/openspaces/core/GigaSpace.html Its time the API was cleaned up. Take the write method for instance:
<T> LeaseContext<T> write(T entry, long lease, long timeout, int modifiers) throws DataAccessException
These are the things I dislike about it:
- The long timeout and lease don’t have units declared. See my previous blog where I show a good way to supply durations.
- The documentation is terrible, it does not mention what units the timeout are in, I had to navigate to LeaseContext to understand the lease, and find Lease.FOREVER. As I write this I still do not know how to set a maximum or minimum timeout. Perhaps 0, null? Not sure. What happens if you set a minus value?
- The method has a mode in the form of modifiers. Modifiers is a bad name but I would rather delete it than change the name. The mode is not a great way to communicate what your method does, but this one is particularly bad because it can effect what might be returned and possibly the types of exception that might get thrown.
- UpdateModifiers is also not an enum but a constants class. As such the evil modifier is not even type or boundary safe.
UpdateModifiers.UPDATE_OR_WRITE . If your very lucky you might get a lease back. If you have successfully written (a new object or object with no id.) you get null. If you update the lease contains the previous value. But hang on there is a flag! I hate flags. The NoWriteLease if set causes the method to return null in all situations. I wonder how you set that, the documentation has no link.
UpdateModifiers.WRITE_ONLY Could throw EntryAlreadyInSpaceException for objects that have an id and your writing a duplicate.
So as you can see, if I call this method changing the mode might mean I have to change the post execution traps, null handling etc. Very easy to introduce a bug inadvertently.
If anyone from GigaSpace or OpenSpace is reading, sorry but its been a long day and I had to walk 4 miles through the snow to get home! While you amending the API onto an otherwise excellent product, could you update your more general documentaiton. Its very use case based. This is great when my use case matches your documentation, but most of the time this is not the case. So it becomes a nightmare picking pieces from here and there hoping its all going to work. I drive everything from tests but it gets a bit tedious when my tests fail because my assumptions are wrong.
Anyway before this blog turns into a rant. It may already be too late, sorry. 
For discussion – Suggestion for a new API
write(T entry
, long lease, TimeUnit leaseUnit
, long timeout, TimeUnit timeoutUnit)
writeOrUpdate(T entry
, long lease, TimeUnit leaseUnit
, long timeout, TimeUnit timeoutUnit)
update(T entry
, long lease, TimeUnit leaseUnit
, long timeout, TimeUnit timeoutUnit)
partialUpdate(T entry
, long lease, TimeUnit leaseUnit
, long timeout, TimeUnit timeoutUnit)
Ditto that. I’ve spent so long struggling with the GigaSpaces documentation I’ve recommended to our company that we try Terracotta. The documentation is woeful. Not only that, but separation of concerns is never clear.
My other pet hate is that whenever you contact support their standard response is “provide a test case”. I would if you had supplied proper documentation to allow me to do this !! There is also an arrogance about the support that insinuates that you are stupid for asking the question.
IMHO no matter how good the product is, it will never be more than a niche product for those obviously brighter and cleverer than me who are able to figure out how to use it.
Paul. You probably know this and it does not justify the test case thing but….its fairly easy to put together unit test cases that bring up GS in the test. I use this technique to build my own services that read and write from GS.
Hi Martin
Thanks for your valuable feedback. I think you make a valid point.
As a first step, we will make sure to improve the JavaDocs to better explain the meaning of each argument.
And now to the detailed explanation: the OpenSpaces API is about 3 years old, and was originally modeled after our older JavaSpaces API. When we created the OpenSpaces API, we wanted to provide the smoothest migration path for our existing customers, and therefore wanted to keep the amount of changes minimal. Naturally, this came in some cases at the expense of creating a more modern and easier to use API.
We have considered to change this API in recent releases, but eventually decided not to do so because we didn’t want to further overload the existing API, such as the GigaSpace interface for example. However, we will at some point in the future have to deprecate older APIs, and we will definitely take your input into consideration in our upcoming releases.
Note that this is not the case for our newer APIs, such as the administration and monitoring API, which makes use of method chaining, TimeUnit and other more modern patterns:
http://www.gigaspaces.com/wiki/display/XAP7/Administration+and+Monitoring+API
Uri (Product Manager at GigaSpaces)
This makes a lot of sense. The sooner you can find time to re-factor them the better. I believe it will help with your market penetration if you can sort out this and improve the documentation.
I for one would happily put up with some deprecation as long as its clear what is replacing the deprecation.