Community
Participate
Working Groups
Apparently, there's an IBM guideline that messages should have message ids. Furthermore, IBM product teams also require that message ids exist (and are the same as in previous releases) because they provide customers with a list/database of id's to help.
I'm also going to use this defect to share common messages in a central location so that duplication can be avoided.
marking this as api breaking since the SimpleSystemMessage constructor will now take a message id.
But I thought that the ID is not mandatory? There could be messages without an ID, no? Because then you could have two constructors (one with ID and one without), and it would not be API breaking.
Remember that at places, RSE API requires extenders to use the SystemMessage interface, e.g. when throwing a SystemMessageException. There are also non-IBM extenders, who don't understand message id's and don't want to be forced to add a dummy id like "9999".
I've committed the changes to cvs. The SimpleSystemMessage constructors now take as their second argument the message id. Message ids for the current RSE messages are as they have been in the past (i.e "RSEG1001", etc.). I'm using constants for these id's in most places. I've created CommonMessages.java, CommonMessages.properties and ICommonMessageIds.java to store the reused items.
Actually this is not a breaking API change, because SimpleSystemMessage was only introduced in 3.0M5 - we're counting a "breaking" only if it was in a released version like 2.0, we're not counting breakage against milestones. I'd suggest that message IDs should be grouped in few interfaces only, i.e. the directly embedded Strings like "RSEF1003" in RemoteFolderNotEmptyException should probably go into IRSEServicesMessageIds.java --> Use a common naming scheme for all interfaces that hold Message ID's, in order to make it easy for automated tooling to find out all message ID's in use such that duplication can be avoided etc New API added with this bug: * org.eclipse.rse.services/clientserver CommonMessages ICommonMessageIds
Dave - what do you think about providing a constructor without message ID, which would automatically provide a default/dummy id?
(In reply to comment #7) > Dave - what do you think about providing a constructor without message ID, > which would automatically provide a default/dummy id? The thing I'd worry about with a non-id constructor is that developers would be inclined to avoid using ids when using either common or uncommon messages. Aside from identifying a message as unique and being able to cross reference a message id with documentation, the id is also being used as the title for SystemMessageDialog.
Fair enough, but you can't force IDs on non-IBM products. We know that we'll use IDs properly inside RSE. So why force IDs on extenders?
I'd at least want to discourage developers from not using ids. I'm not sure how to do that effectively other than via the constructor. Would you suggest just using javadoc for this purpose?
Yes Javadoc should be sufficient. For your IBM products, you can also Trace every use of the constructor without ID, and since you have the plugin id available, you can even know the culprit. Note that in an Open Source World, where we have no idea who extends us and in what respect, we have no chance to come up with any useful global message ID's. That's why Ecipse IStatus uses an (int) as "plug-in specific status code" and gives the plugin every freedom they want for using that status code. What we could do is mimic Eclipse Status and update Javadoc of the SimpleSystemMessage saying that the message ID is plug-in specific. But then, that would not be true for the IBM products where the message ID is supposed to be globally unique. In the end, that's something you'll need to discuss at IBM... I just want to avoid confusion among Open Source Extenders who would not know what format, type or range of IDs they are allowed to use for SimpleSystemMessage.
(In reply to comment #11) > Yes Javadoc should be sufficient. > For your IBM products, you can also Trace every use of the constructor without > ID, and since you have the plugin id available, you can even know the culprit. > Note that in an Open Source World, where we have no idea who extends us and in > what respect, we have no chance to come up with any useful global message ID's. > That's why Ecipse IStatus uses an (int) as "plug-in specific status code" and > gives the plugin every freedom they want for using that status code. > What we could do is mimic Eclipse Status and update Javadoc of the > SimpleSystemMessage saying that the message ID is plug-in specific. But then, > that would not be true for the IBM products where the message ID is supposed to > be globally unique. > In the end, that's something you'll need to discuss at IBM... I just want to > avoid confusion among Open Source Extenders who would not know what format, > type or range of IDs they are allowed to use for SimpleSystemMessage. I've added the new constructors, some javadoc and trace statements where the message id is not specified.
The tracing doesn't work as currently implemented because clientserver.jar must also run stand-alone in the dstore server, without any Eclipse Tracing Infrastructure. After thinking about this again, I guess I'd be OK with requiring a message-id in the constructors. Question is how to properly write the Javadocs, because it must be clear for non-IBM extenders that 1.) this message-id is something that the plugin can freely choose 2.) Yet there must not be any namespace collision with message id's owned by IBM Eclipse "IStatus" solves this by binding the message id (aka status code) to the plugin id, and make the namespace "local" to the plugin. Please think about possible solutions for this in RSE.
What do you think about this approach for SimpleSystemMessage: if (pluginID==null) { messageID must be a globally unique id } else { messageID may be "local" relative to plugin id } Title of dialogs and text in logs only shows messageID if globally unique, or it shows "pluginID:messageID" if not globally unique. That way, IBM could use globally unique message ID's with a "null" pluginID and other contributors / extenders could use their plugin-local ID's without polluting the global namespace or risking collisions.
(In reply to comment #14) > What do you think about this approach for SimpleSystemMessage: > if (pluginID==null) { > messageID must be a globally unique id > } else { > messageID may be "local" relative to plugin id > } > Title of dialogs and text in logs only shows messageID if globally unique, or > it shows "pluginID:messageID" if not globally unique. > That way, IBM could use globally unique message ID's with a "null" pluginID and > other contributors / extenders could use their plugin-local ID's without > polluting the global namespace or risking collisions. As discussed in committer meetings, I'm not so sure about this approach. I find it useful to have both a pluginID as well as a global message ID. A number of our messages are used in several plugins so that the information provided by the pluginID is helpful. Almost all of the current RSE messages have a global id and a plugin ID right now. If we were to change this so that you could either have a global id (without a plugin id) or a plugin Id and a relative message ID, then we would have to set all the pluginIDs that are passed in now to null.
Then we need a different kind of convention, e.g. all global message ids need to start with "RSE" whereas anything else is considered non-global. Would that work?
(In reply to comment #16) > Then we need a different kind of convention, e.g. all global message ids need > to start with "RSE" whereas anything else is considered non-global. Would that > work? I think I'd be okay with that.
Ok so I propose capturing this information in the Javadocs.
I filed bug 226773 to handle the remaining task of writing Javadoc to specify what message ID's are allowed. Since that one is now tracked separately, I'm closing this.
