P4
A DESCRIPTION OF THE PROBLEM :
Context
The "Introduction" section [1] of The Java™ Tutorials' "Creating Extensible Applications" trail introduces important terms and concepts about Java™ SE's Service Provider Interface (SPI) mechanism.
The body of the lesson incorrectly uses the terms interchangeably with one another. Such confusion makes a less-than-straightforward lesson, even more of a challenge to fully understand.
Consider This
In the tutorial's sample code, the `DictionaryService` entry point singleton is a concrete class ; i.e., it is an *implementation*. However, the `Dictionary` Service Provider *Interface* is just that — an interface; not an *implementation*
——
Documentation Bug #1
Given this paragraph in the "Dictionary Service Example" [2] section:
"...shows you how to implement a `Dictionary` service, create `Dictionary` service providers that add additional dictionaries, and create a simple `Dictionary` service client that tests the service..."
——
Proposed Correction #1
Consider whether alternative wording would be less confusing to inexperienced learners who may be new to the trail's concepts:
"...shows you how to implement a `DictionaryService` entry point to the dictionary service, create `ExtendedDictionary` and `GeneralDictionary` service providers that add additional dictionaries, and create a simple `DictionaryDemo` service client that tests the service..."
——
Documentation Bug #2
The section "4. Register Service Providers" [3] incorrectly instructs [emphasis mine]:
"...To register your service provider, you create a provider configuration file ... The name of the configuration file is the fully qualified class name of *the service provider*..."
It has already been established at that point in the lesson that the fully qualified name of the service providers are `dictionary.GeneralDictionary` and `dictionary.ExtendedDictionary`. The fully qualified name of the service provider *interface* is `dictionary.spi.Dictionary`.
——
Proposed Correction #2
The tutorial's wording should, therefore, be corrected to read [emphasis mine]:
"...The name of the configuration file is the fully qualified class name of the service provider *interface*..."
—
[1] https://bit.ly/spiNtro
[2] https://bit.ly/spiDemoEg
[3] https://bit.ly/spiRegImpls
Context
The "Introduction" section [1] of The Java™ Tutorials' "Creating Extensible Applications" trail introduces important terms and concepts about Java™ SE's Service Provider Interface (SPI) mechanism.
The body of the lesson incorrectly uses the terms interchangeably with one another. Such confusion makes a less-than-straightforward lesson, even more of a challenge to fully understand.
Consider This
In the tutorial's sample code, the `DictionaryService` entry point singleton is a concrete class ; i.e., it is an *implementation*. However, the `Dictionary` Service Provider *Interface* is just that — an interface; not an *implementation*
——
Documentation Bug #1
Given this paragraph in the "Dictionary Service Example" [2] section:
"...shows you how to implement a `Dictionary` service, create `Dictionary` service providers that add additional dictionaries, and create a simple `Dictionary` service client that tests the service..."
——
Proposed Correction #1
Consider whether alternative wording would be less confusing to inexperienced learners who may be new to the trail's concepts:
"...shows you how to implement a `DictionaryService` entry point to the dictionary service, create `ExtendedDictionary` and `GeneralDictionary` service providers that add additional dictionaries, and create a simple `DictionaryDemo` service client that tests the service..."
——
Documentation Bug #2
The section "4. Register Service Providers" [3] incorrectly instructs [emphasis mine]:
"...To register your service provider, you create a provider configuration file ... The name of the configuration file is the fully qualified class name of *the service provider*..."
It has already been established at that point in the lesson that the fully qualified name of the service providers are `dictionary.GeneralDictionary` and `dictionary.ExtendedDictionary`. The fully qualified name of the service provider *interface* is `dictionary.spi.Dictionary`.
——
Proposed Correction #2
The tutorial's wording should, therefore, be corrected to read [emphasis mine]:
"...The name of the configuration file is the fully qualified class name of the service provider *interface*..."
—
[1] https://bit.ly/spiNtro
[2] https://bit.ly/spiDemoEg
[3] https://bit.ly/spiRegImpls