Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 376520

Summary:	future proofing extension point API
Product:	[ECD] Orion	Reporter:	Susan McCourt <susan>
Component:	Client	Assignee:	Simon Kaegi <simon_kaegi>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	normal
Priority:	P3	CC:	john.arthorne, mamacdon, simon_kaegi
Version:	unspecified
Target Milestone:	5.0 M1
Hardware:	PC
OS:	Windows 7
Whiteboard:

Description Susan McCourt

2012-04-11 14:30:45 EDT

Before we ship 0.5, we should look at all of our extension point API and see if any minor changes might help to future proof it.

By example:
- Mark moved some content assist properties into a "context" object which will allow us to add more contextual information if needed in the future
- validationProperties changed from a fixed key/value specification to an object so that additional properties could be added.
- the save tokens in orion.page.content changed from arrays to an object.

Anywhere that we now use a single value, or an array, etc. to express some fixed set of properties, we should instead use an object with named properties so that we can grow the API as needed.

We may have to do a similar pass for other API (calls into services) but that presumes we know what our API is.  I mention extension points because that is definitely API.

Comment 1 John Arthorne

2012-04-11 15:01:01 EDT

Well, adding new arguments in the future isn't a breaking change in JavaScript. But, I agree a property object is an easier to use API in the long run in many cases.

Comment 2 Susan McCourt

2012-04-11 17:29:08 EDT

(In reply to comment #1)
> Well, adding new arguments in the future isn't a breaking change in JavaScript.
> But, I agree a property object is an easier to use API in the long run in many
> cases.

adding new arguments is not breaking, but changing the order is, so a property object is a bit more future proof/flexible.

The arrays are the ones I'm particularly leery of.  For example I changed

replacements: [["match", "replacement"], ["match2", "replacement2"]]

to

replacements: [{source: "match", replacement: "replacement"}, {source: "match2", replacement: "replacement2"}]

This lets us add properties to replacements in the future, such as flags, etc.  Without doing this, we'd have to start introducing new top level properties like:

replacementsFlags: ["g", "g"] rather than

replacements: [{source: "match", replacement: "replacement", flags: "g"}]  etc...

Comment 3 Simon Kaegi

2012-10-03 16:38:30 EDT

This is important but not for our guarantees in 1.0. Moving to 2.0 M1 where we should be straightening out more of these API.

Comment 4 John Arthorne

2015-05-05 14:51:35 EDT

Closing as part of a mass clean up of inactive bugs. Please reopen if this problem still occurs or is relevant to you. For more details see:

https://dev.eclipse.org/mhonarc/lists/orion-dev/msg03444.html