Global FS variables, another suggestion

[Thilo Goetz <tw...@gmx.de>]

I have another suggestion that I believe

- is user friendly,
- is fully backward compatible,
- does not involve changes to our descriptors,
- is not too kludgy,
- and only conservatively extends the API.

I hope I have your attention ;-)

I suggest we introduce a new built-in type and new built-in index as 
follows.

- a type uima.cas.FsVariable that inherits from uima.cas.TOP with 
features name:String, type:String and value:TOP.

- a built-in set index over FsVariable, sorted by the name feature.

One could imagine various approaches to APIs over these basic 
datastructures.  The simplest approach would be to add

CAS.setFsVariable(String name, FS fs)
CAS.getFsVariable(String name):FS

setFsVariable() would check if the variable existed.  If so, it would 
make sure the new value has the same type as the previous one (issues 
surrounding null values need to be taken care of).  This would be the 
dynamic approach to variable declaration.

Alternatively, we could add more APIs:

CAS.declareFsVariable(String name, Type type)
CAS.isFsVariable(String name):boolean
CAS.getFsVariableType(String name):Type

declareFsVariable() would declare the variable and throw an exception if 
it already existed.  setFsVariable() and getFsVariable() would also 
throw exceptions for non-declared variables.  This would allow us to 
ensure that a variable can be declared in one place only. 
isFsVariable() would check if a variable of that name had been declared 
already.  getFsVariableType() would do the obvious.

I personally like this explicit approach to typing better, but it does 
make the API more verbose.

The whole mechanism is completely transparent as it only uses existing 
features.  All data is kept in the CAS, there is nothing 
CAS-implementation specific here.  All the FsVariable APIs could be 
implemented using public APIs only, so are easily portable to our other 
implementation platforms if desired.  There is no problem with 
serialization as there are no changes to the CAS.

Please let me know if you think this is a good idea, and if so, if 
you're in favor of the dynamically typed or the pseudo-statically typed 
version.

--Thilo

Re: Global FS variables, another suggestion

[Thilo Goetz <tw...@gmx.de>]

Adam Lally wrote:
> On 1/11/07, Michael Baessler <mb...@michael-baessler.de> wrote:
>> Thilo Goetz wrote:
>> > CAS.declareFsVariable(String name, Type type)
>> > CAS.isFsVariable(String name):boolean
>> > CAS.getFsVariableType(String name):Type
>> I would like to have an additional method like
>>
>> CAS.getFsVariableForType(Type type):FS
>>
>> so that an analysis component do not have to know the variable name, it
>> only have to know that for a certain type a variable exist that 
>> contains the
>> FS of interest and can retrieve it.
>>
> 
> I think Michael is onto the same point that concerns me.  To use this
> feature, components have to agree on what variable names they are
> going to use.  So we're creating another kind of dependency that I
> believe should be documented in the capabilities.  Sure, people could
> build this themselves already, but if we make it built-in then we're
> strongly encouraging its use and should consider all the implications.
> If we had more expressive capability spec (so you could say I
> create/require an instance of type FsVariable with name="Foo") then
> that might be a way to go.

I guess we could do that in addition.  How would you imagine this would 
work?

I'm mainly addressing a practical problem here, and want to give people 
a viable alternative to modifying the DocumentAnnotation.  I think this 
approach is fairly forward-compatible as well, in the sense that it can 
later be strengthened with descriptor-based integrity constraints.

> 
> I don't think getFsVariableForType(Type) would completely address the
> issue.  There can be more than one variable for the same type, so the
> downstream component would still not have any idea which one it wanted
> to use.

True, but it's better than anything we have today.  At least this way 
two components *can* communicate, if they want to.  If you want 
additional safety, you pass the variable name around as a parameter. 
That's the best way to ensure that everybody is using the same one.

--Thilo

Re: Global FS variables, another suggestion

[Adam Lally <al...@alum.rpi.edu>]

On 1/11/07, Michael Baessler <mb...@michael-baessler.de> wrote:
> Thilo Goetz wrote:
> > CAS.declareFsVariable(String name, Type type)
> > CAS.isFsVariable(String name):boolean
> > CAS.getFsVariableType(String name):Type
> I would like to have an additional method like
>
> CAS.getFsVariableForType(Type type):FS
>
> so that an analysis component do not have to know the variable name, it
> only have to know that for a certain type a variable exist that contains the
> FS of interest and can retrieve it.
>

I think Michael is onto the same point that concerns me.  To use this
feature, components have to agree on what variable names they are
going to use.  So we're creating another kind of dependency that I
believe should be documented in the capabilities.  Sure, people could
build this themselves already, but if we make it built-in then we're
strongly encouraging its use and should consider all the implications.
 If we had more expressive capability spec (so you could say I
create/require an instance of type FsVariable with name="Foo") then
that might be a way to go.

I don't think getFsVariableForType(Type) would completely address the
issue.  There can be more than one variable for the same type, so the
downstream component would still not have any idea which one it wanted
to use.

-Adam

Re: Global FS variables, another suggestion

[Thilo Goetz <tw...@gmx.de>]

Michael Baessler wrote:
> Thilo Goetz wrote:
>> CAS.declareFsVariable(String name, Type type)
>> CAS.isFsVariable(String name):boolean
>> CAS.getFsVariableType(String name):Type
> I would like to have an additional method like
> 
> CAS.getFsVariableForType(Type type):FS
> 
> so that an analysis component do not have to know the variable name, it 
> only have to know that for a certain type a variable exist that contains 
> the
> FS of interest and can retrieve it.
> 
> -- Michael
> 

I see.  However, since there can be more than one variable for each 
type, it would have to be something like this:

CAS.getFsVariablesForType(Type type):String[]

which returns an array of variable names.  If there happens to be 
exactly one variable declared for a given type, this would be a way of 
retrieving that variable.

--Thilo

Re: Global FS variables, another suggestion

[Michael Baessler <mb...@michael-baessler.de>]

Thilo Goetz wrote:
> CAS.declareFsVariable(String name, Type type)
> CAS.isFsVariable(String name):boolean
> CAS.getFsVariableType(String name):Type
I would like to have an additional method like

CAS.getFsVariableForType(Type type):FS

so that an analysis component do not have to know the variable name, it 
only have to know that for a certain type a variable exist that contains the
FS of interest and can retrieve it.

-- Michael

Re: Global FS variables, another suggestion

[Jörn Kottmann <ko...@gmail.com>]

> Having not heard a user request for global variables, I'm a little
> fuzzy on the use case.

Imagine an Annotator which is a spam filter, it has to
put a tag to the CAS which say spam or no_spam.

The document language is also an example for a global variable.

Re: Global FS variables, another suggestion

[Thilo Goetz <tw...@gmx.de>]

Eddie Epstein wrote:
> Having not heard a user request for global variables, I'm a little
> fuzzy on the use case. 

It usually goes by the name of "singletons", I'm sure you've heard that one.

 > However, if I understand correctly what is
> suggested is a combination of:
> 
> 1. a new built in type with two features.

Three, actually.

> 2. a slight variation on the set index, where instead of silently
> ignoring a "duplicate" FS being added to the index, an exception is
> thrown.

It's not a variation on a set index, it's just a plain old set index.

> 3. custom APIs for working with the features of this type.

Yes.  You might call them convenience functions ;-)

> 
> Is this right?
> Eddie

Re: Global FS variables, another suggestion

[Adam Lally <al...@alum.rpi.edu>]

On 1/11/07, Eddie Epstein <ea...@gmail.com> wrote:
> Having not heard a user request for global variables, I'm a little
> fuzzy on the use case.

I think one use case is the "singleton" use case.  You could define a
"global variable" called myapp.documentMetadata and set its value to
an instance of myTypeSystem.DocumentMetadata.  Then all your
annotators could access it by getting the value of this global
variable.

-Adam

Re: Global FS variables, another suggestion

[Eddie Epstein <ea...@gmail.com>]

Having not heard a user request for global variables, I'm a little
fuzzy on the use case. However, if I understand correctly what is
suggested is a combination of:

1. a new built in type with two features.
2. a slight variation on the set index, where instead of silently
ignoring a "duplicate" FS being added to the index, an exception is
thrown.
3. custom APIs for working with the features of this type.

Is this right?
Eddie

Re: Global FS variables, another suggestion

[Jörn Kottmann <ko...@gmail.com>]

> Jörn, I'm not sure I understand what you mean.  The types need to  
> be declared in the the type system.  Adam thinks that declaring  
> variables in the descriptor is not worth the effort, and I don't  
> know that I disagree with him.  Declaring the variables in the  
> descriptor would have the one benefit that we could check for  
> multiple declarations at initialization/packaging time.  On the  
> other hand, my current proposal is more dynamic as you can check if  
> a variable has been declared, and if not, declare it yourself.
>
> Did that answer your question?

Yes, sorry that I did not made it clear in my question.

Re: Global FS variables, another suggestion

[Thilo Goetz <tw...@gmx.de>]

Jörn Kottmann wrote:
>> Please let me know if you think this is a good idea, and if so, if 
>> you're in favor of the dynamically typed or the pseudo-statically 
>> typed version.
> 
> Can you explain what is the reason to not declare the type inside the 
> type system ?
> 
> Thanks,
> Jörn

Jörn, I'm not sure I understand what you mean.  The types need to be 
declared in the the type system.  Adam thinks that declaring variables 
in the descriptor is not worth the effort, and I don't know that I 
disagree with him.  Declaring the variables in the descriptor would have 
the one benefit that we could check for multiple declarations at 
initialization/packaging time.  On the other hand, my current proposal 
is more dynamic as you can check if a variable has been declared, and if 
not, declare it yourself.

Did that answer your question?

--Thilo

Re: Global FS variables, another suggestion

[Jörn Kottmann <ko...@gmail.com>]

> Please let me know if you think this is a good idea, and if so, if  
> you're in favor of the dynamically typed or the pseudo-statically  
> typed version.

Can you explain what is the reason to not declare the type inside the  
type system ?

Thanks,
Jörn