[Phptmapi-discuss] Proposal: PHPTMAPI 2.0.1

[Johannes S. <jsc...@t8...>]

Hi all,
I'd like to discuss a proposal for version 2.0.1 of PHPTMAPI which 
includes the following changes:

1) Retrieval of TopicMapSystemFactory's implementation in 
TopicMapSystemFactory::newInstance() [1] (thanks Alain):
In current version 2.0 the private static 
TopicMapSystemFactory::getImplementationClass() returns an instance of 
the implemented TopicMapSystemFactory by using the "new" operator - 
however an instance should be created exclusively in 
TopicMapSystemFactory::newInstance() by calling 
TopicMapSystemFactoryImpl::newInstance().
Thus, the proposed change here is to rename getImplementationClass() as 
getImplementationClassName() which only returns the implementation class 
name - and not an instance. The class name is then used in newInstance() 
to retrieve an instance of the concrete TopicMapSystemFactory.

I have attached a patch for better illustration.

2) Throw InvalidArgumentException in TypeInstanceIndex::getTopics() [2]
Throw an InvalidArgumentException in TypeInstanceIndex::getTopics() if 
param. $types does not exclusively contain topics. 
InvalidArgumentException is part of Standard PHP Library (SPL).

3) Force type "array" for parameter $themes in ScopedIndex methods and 
extend PHP docs [3]:
The methods should be changed as follows:
a) getAssociations($themes, $matchAll) -> getAssociations(array $themes, 
$matchAll)
b) getNames($themes, $matchAll) -> getNames(array $themes, $matchAll)
c) getOccurrences($themes, $matchAll) -> getOccurrences(array $themes, 
$matchAll)

All these methods throw an InvalidArgumentException if $themes does not 
exclusively contain topics. The docs should be further extended 
regarding the unconstrained scope: "If themes' length = 0, themes is 
interpreted as the unconstrained scope."

Here is an example for getAssociations():

    /**
     * Returns the {@link Association}s in the topic map whose scope 
property
     * equals one of those <var>themes</var> at least. If themes' length 
= 1,
     * <var>matchAll</var> is interpreted <var>true</var>. If themes' 
length = 0,
     * <var>themes</var> is interpreted as the unconstrained scope.
     * The return value may be an empty array but must never be 
<var>null</var>.
     *
     * @param array Scope of the {@link Association}s to be returned.
     *                 If <var>themes</var> is an empty array all {@link 
Association}s in the
     *                 unconstrained scope are returned.
     * @param boolean If true the scope property of an association must 
match all themes,
     *        if false one theme must be matched at least. If themes' 
length = 1, matchAll
     *        is interpreted true.
     * @return array An array containing {@link Association}s.
     * @throws InvalidArgumentException If <var>themes</var> does not 
exclusively contain
     *                 {@link Topic}s.
     */

d) getVariants($themes, $matchAll) -> getVariants(array $themes, $matchAll)

getVariants throws an InvalidArgumentException if $themes is an empty 
array, or if $themes does not exclusively contain topics.

Thoughts?

Best regards,
Johannes

[1] 
http://phptmapi.svn.sourceforge.net/viewvc/phptmapi/phptmapi2.0/trunk/core/TopicMapSystemFactory.class.php?revision=32&view=markup
[2] 
http://phptmapi.svn.sourceforge.net/viewvc/phptmapi/phptmapi2.0/trunk/index/TypeInstanceIndex.interface.php?revision=27&view=markup
[3] 
http://phptmapi.svn.sourceforge.net/viewvc/phptmapi/phptmapi2.0/trunk/index/ScopedIndex.interface.php?revision=9&view=markup