Hello All,
We are currently in the process of getting the 9.1 SP4 javadocs posted. As soon as they are available in the library, we link them to the documentation page. The reason for this is a number of APIs have changed that I have run across in the last few weeks, and so I want to make sure everyone has access to these for addressing any issues that may pop up.
In the meantime, here are the changes I have found so far. If anyone else has any others, please feel free to add them here. We are working on ways to improve the process of change management between releases/service packs, but until those improvements come to fruition, we'll do our best to inform you as we learn of these things.
Changes
There may be more, but these are the ones I've come across recently. Again, please feel free to add anything you have found as well.
I will post these somewhere on edugarage with a list of best practices to follow with each release to avoid these things. When I figure out where to put it, I'll post the link here.
Thanks,
-scott
Scott,
Great job on the post mortem notification. Is there a way to keep developers updated on the upcoming deprecated API removal? It would have been useful in 9.1 sp1 to get a list of planned API drop.
Just a bit more time before the community users see issues.
Also, why not drop API in major releases, not service packs?
Szymon
There may be others, this is what I could easily retrieve from my Subversion logs.
smachaje: Scott, Great job on the post mortem notification. Is there a way to keep developers updated on the upcoming deprecated API removal? It would have been useful in 9.1 sp1 to get a list of planned API drop. Just a bit more time before the community users see issues. Also, why not drop API in major releases, not service packs? Szymon
Hi Szymon,
We are working to put processes in place to catch these changes prior to the release being made available to avoid issues such as these in the future. As far as I can tell, these drops weren't planned ahead of time, so we are also working to put in place a strict deprecation policy. That policy should, in my opinion, be as you suggest, but unfortunately, it's not just up to me. That said, once we have the policy in place, we can then pass that knowledge to the community so you will at least know what to expect. Then it will be up to us to make sure the policy is adhered to.
As technology changes and the APIs become more and more utilized, the need for policy and procedure has grown exponentially. We have an internal team working through these and other issues to do just that.
In that spirit, I have posted the 9.1 SP4 Javadocs in the documentation section.
pyotr: blackboard.cms.filesystem.CSContext.commit() now throws XythosException the contents of a TreeNode (not in public API) now must be enclosed in a <a> tag otherwise the dynamictree javascript will silently throw an exception (and your tree won't work, obviously) findFileSystemEntryByEmbeddedXythosId(String) was removed from blackboard.cms.xythos.XythosFileSystemUtil (not in public API), findFileSystemEntryByXythosId(String, Context) is not a direct replacement, it requires the String to be in a different format the constructor of blackboard.admin.cxutil.ContentCopier (not in public API) has two additional boolean arguments updateOverride in blackboard.platform.gradebook2.GradebookManager now takes FormattedText instead of String for feedback blackboard.data.course.CourseQuota is deprecated without replacement There may be others, this is what I could easily retrieve from my Subversion logs.
Duly noted on the XythosException and CourseQuota. For the others, that is unfortunately the risk that comes with the reward private APIs afford. That said, still valuable information for others that may have used them as well, so thankss for the info!
Scott Hurrey: In that spirit, I have posted the 9.1 SP4 Javadocs in the documentation section.
Thanks John, but I notice CourseQuota is completely missing from the new docs... I really liked that some of the @deprecated texts included the service pack number ("Since 9.1SP4"), much appreciated, this makes the "Deprecated API" page in the javadoc very useful.
Scott Hurrey: Duly noted on the XythosException and CourseQuota. For the others, that is unfortunately the risk that comes with the reward private APIs afford. That said, still valuable information for others that may have used them as well, so thankss for the info!
Yup, and I am not complaining (maybe just softly grumbling :P). Besides giving other developers a heads-up (I know some of the above is used by others) I thought it might give Blackboard some ideas of where to extend the public API (nudge nudge). The changed behaviour of the TreeNode javascript was a pain to diagnose but the other changes were easily remedied.
As to when Blackboard can / should drop deprecated API, I would say only in even numbered service packs (the odd numbered ones are bugfixes only, no new features) and preferably skipping one even release. My "perfect" deprecation text would therefore be:
@deprecated Since 9.1SP4; will be removed in 9.1SP8. Use ContentHandlerInfo enum instead
ContentHandlerInfo
GroupDbPersister.deleteById() now needs "modify" permission on GroupAssignment in the bb-manifest. Changes like this are not easily found (recompiling against the latest Blackboard JAR files flushes out API changes), it required a very specific situation to bump into this one.
String strReturnUrl = PlugInUtil.getEditableContentReturnURL(courseDoc.getParentId());
should now be
String strReturnUrl = PlugInUtil.getEditableContentReturnURL(courseDoc.getParentId(),courseDoc.getCourseId());
Thanks to John Porter for finding this and bringing it to our attention.
And Peter, I actually asked for that sort of deprecation comment in the javadocs, but I don't think it will go that far. Instead, I think we will just try to create and document a strict deprecation policy that we can then post so that you (and we) can look at a deprecated since and compare to the policy, and know we have X number of releases, or the next major release, or whatever that criterion ends up being.