You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by og...@apache.org on 2011/11/30 09:41:38 UTC
svn commit: r1208325 - /incubator/stanbol/trunk/commons/solr/README.md
Author: ogrisel
Date: Wed Nov 30 08:41:37 2011
New Revision: 1208325
URL: http://svn.apache.org/viewvc?rev=1208325&view=rev
Log:
DOC: typos / cosmetics in the Solr / OSGi documentation
Modified:
incubator/stanbol/trunk/commons/solr/README.md
Modified: incubator/stanbol/trunk/commons/solr/README.md
URL: http://svn.apache.org/viewvc/incubator/stanbol/trunk/commons/solr/README.md?rev=1208325&r1=1208324&r2=1208325&view=diff
==============================================================================
--- incubator/stanbol/trunk/commons/solr/README.md (original)
+++ incubator/stanbol/trunk/commons/solr/README.md Wed Nov 30 08:41:37 2011
@@ -1,5 +1,4 @@
-Stanbol Commons Solr
-====================
+# Stanbol Commons Solr
Solr is used by several Apache Stanbol components. The Apache Stanbol Solr Commons artifacts provide a set of utilities that ease the use of Solr within OSGi, allow the initialization and management of Solr indexes as well as the publishing of Solrs RESTful interface on the OSGi HttpService.
@@ -7,8 +6,7 @@ Although this utilities where implemente
"stanbol.commons".
-Solr OSGi Bundle
-----------------
+## Solr OSGi Bundle
The "org.apache.commons.solr.core" bundle currently includes all dependencies required by Solr and also exports the client as well as the server API. For details please have a look at the pom file of the "solr.core" artifact.
@@ -17,11 +15,11 @@ Please note also the exclusion list, bec
If you require an additional Library that is currently not included please give us a short notice on the stanbol-dev mailing list.
-Solr Server Components
-----------------------
+## Solr Server Components
This section provides information how to managed and get access to the server side CoreContainer and SolrCore components of Solr.
+
### Accessing CoreContainers and SolrCores
All CoreContainer and SolrCores initialized by the Stanbol Solr framework are registered with the OSGi Service Registry. This means that other Bundels can obtain them by using
@@ -29,7 +27,7 @@ All CoreContainer and SolrCores initiali
CoreContainer defaultSolrServer;
ServiceReference ref = bundleContext.getServiceReference(
CoreContainer.class.getName())
- if(ref != null) {
+ if (ref != null) {
defaultSolrServer = (CoreContainer) bundleContext.getService(ref);
} else {
defaultSolrServer = null; //no SolrServer available
@@ -39,6 +37,7 @@ It is also possible to track service reg
The above Code snippet would always return the SolrServer with the highest priority (the highest value for the "service.ranking" property). However the OSGi Service Registry allows also to obtain/track service by the usage of filters. For specifying such filters it is important to know what metadata are provided when services are registered with the OSGi Service Registry.
+
#### Metadata for CoreContainer:
* **org.apache.solr.core.CoreContainer.name**: The name of the SolrServer. The name MUST BE provided for each Solr CoreContainer registered with this framework. It is a required field for each configuration. If two CoreContainers are registered with the same name the "service.ranking" property shall be used to determine the current active CoreContainer for an request. However others registered for the same name may be used as fallbacks. The container name is used as a URL path component when the `publishREST` parameter is true. It is recommended to use lowercase names without non ASCII characters.
@@ -48,6 +47,7 @@ The above Code snippet would always retu
* **service.ranking**: The OSGi "service.ranking" property is used to specify the ranking of a CoreContainer. The CoreContainer with the highest ranking is considered as the default server and will be returned by calls to bundleContext.getServiceReference(..) without the use of an filter.
* **org.apache.solr.core.CoreContainer.publishREST**: Boolean switch that allows to enable/disable the publishing of the Solr RESTful API on "http://{host}:{port}/solr/{server-name}". Requires the "SolrServerPublishingComponent" to be active.
+
#### Metadata for SolrCores:
* **org.apache.solr.core.SolrCore.name**: The name of the SolrCore as registered with the CoreContainer
@@ -86,10 +86,12 @@ Configurations need to include the follo
**NOTE:** Keep in mind that of the RESTful API of the SolrServer is published users might use the Admin Request handler to manipulate the SolrConfiguration. In such cases the metadata provided by the ServiceReferences for the CoreContainer and SolrCores might get out of sync with the actual configuration of the Server.
+
### ManagedSolrServer
This component allows to manage a multi core Solr server. It provides an API to create, update and remove SolrCores. In addition cores can be activated and deactivated.
+
#### Creating ManagedServerInstances
The ManagedSolrServer uses the ManagedServiceFactory pattern. This means that instances are created by parsing configurations to the OSGi ConfigurationAdmin service. Practically this means that:
@@ -107,6 +109,7 @@ Configurations need to include the follo
**NOTE:** Keep in mind that of the RESTful API of the SolrServer is published users might use the Admin Request handler to manipulate the SolrConfiguration. In such cases the metadata provided by the ServiceReferences for the CoreContainer and SolrCores might get out of sync with the actual configuration of the Server.
+
#### Managing Solr Indexes
This describes how to manage (create, update, remove, activate, deactivate) Indexes on a ManagedSolrServer.
@@ -142,6 +145,7 @@ The following keys are used (see also or
* **Synchronized**: Boolean switch. If enabled the index will be synchronized with the referenced Solr-Index-Archives. That means the DataFileTracker service will be used to periodically track the states of referenced Solr-Index-Archives. This allows to initialize/update and uninitialise managed Solr indexes by simple making Solr-Index-Archives un-/available to the DataFileProvider infrastructure (such as Users copying/deleting files in the "/sling/datafiles" directory).
* **other Properties**: All parsed properties are forwarded to the DataFileProvider/DataFileTracker service when looking for the referenced Solr-Index-Archives. This components might also define some special keys associated with specific functionalities. Please look at the documentation of this services for details.
+
#### Other interesting Notes
* SolrCore directory names created by the ManagedSolrServer use the current date as suffix. If a directory with that name already exists (e.g. because the same index was already updated on the very same day) than an additional "-{count}" suffix will be added to the end.
@@ -149,14 +153,14 @@ The following keys are used (see also or
* Errors that occur during the asynchronous initialization of SolrCores are stored within the IndexingProperties. They can therefore be requested via the API of the ManagedSolrServer but also be looked up within the persistent state of the ManagedSolrServer (see above where such files are located).
-Solr Client Components
-----------------------
+## Solr Client Components
This sections describes how to use Solr servers and indexes referenced and managed by the "org.apache.stanbol.commons.solr" framework.
Principally there are two possibilities: (1) to directly access Solr indexes via the SolrServer Java API and (2) to publish locally managed index on the OSGi HttpService and than use such indexes via the Solr RESTful API.
The Stanbol Solr framework does not provide utilities for accessing remote Solr servers, because this is already easily possible by using SolrJ.
+
### Java API
This describes how to lookup and access a Solr Server initialized by the "org.apache.stanbol.commons.solr" framework. The client side Java API of Solr is defined by the SolrServer abstract class. The implementation used for accessing a SolrCore running in the same JVM is the EmbeddedSolrServer.
@@ -165,6 +169,7 @@ All Solr server (CoreContainer) and Solr
OSGi already provides APIs and utilities to lookup and track registered services. In the following I will provide some examples how to lookup SolrServers registered as OSGi services.
+
#### IndexReference
The IndexReference is a Java class that manages a reference to an Index. It defines a constructor that takes a serverName and coreName. In addition there is a static parse(String ref) method that takes
@@ -185,11 +190,12 @@ To lookup the SolrCore for the reference
bundleContext.getServiceReferences(null, indexReference.getIndexFilter());
+
#### Lookup Solr Indexes
This example shows how to lookup the default CoreContainer and create a SolrServer for the core "mydata".
- ComponentContext context; //typical passed to the activate method
+ ComponentContext context; // typically passed to the activate method
BundleContext bc = context.getBundleContext();
ServiceReference coreContainerRef =
bc.getServiceReference(CoreContainer.class.getName());
@@ -198,66 +204,75 @@ This example shows how to lookup the def
Now there might be cases where several CoreContainers are available and "mydata" is not available on the default one. The "default" refers to the one with the highest "service.ranking" value. In this case we need to know a available property we can use to filter for the right CoreContainer. In this case we assume the index is on a CoreContainer registered with the name "myserver".
- ComponentContext context; //typical passed to the activate method
+ ComponentContext context; // typically passed to the activate method
BundleContext bc = context.getBundleContext();
- //now lets use the IndexReference to create the filter
- IndexReference indexRef = new IndexReference("myserver","mydata");
+
+ // Now let's use the IndexReference to create the filter
+ IndexReference indexRef = new IndexReference("myserver", "mydata");
ServiceReference[] coreContainerRefs = bc.getServiceReferences(
null, indexRef.getServerFilter());
- //TODO: check that coreContainerRefs != null AND not empty!
- //now we have all References to CoreContainers with the name "myserver"
- //Yes one can register several for the same name (e.g. to have fallbacks)
- //let get the one with the highest service.ranking
- Arrays.sort(coreContainerRefs,ServiceReferenceRankingComparator.INSTANCE);
- //create the SolrServer (same as above)
+ // TODO: check that coreContainerRefs != null AND not empty!
+ // Now we have all References to CoreContainers with the name "myserver"
+ // Yes one can register several for the same name (e.g. to have fallbacks)
+ // let get the one with the highest service.ranking
+ Arrays.sort(coreContainerRefs, ServiceReferenceRankingComparator.INSTANCE);
+
+ // Create the SolrServer (same as above)
CoreContainer coreContainer = (CoreContainer) bc.getService(coreContainerRefs[0])
- SolrServer server = new EmbeddedSolrServer(coreContainer,indexRef.getIndex());
+ SolrServer server = new EmbeddedSolrServer(coreContainer, indexRef.getIndex());
In cases where one only knows the name of the SolrCore (and not the CoreContainer) the initialization looks like this.
- ComponentContext context; //typical passed to the activate method
+ ComponentContext context; // typically passed to the activate method
BundleContext bc = context.getBundleContext();
- String nameFilter = String.format("(%s=%s)",SolrConstants.PROPERTY_CORE_NAME,"mydata");
+ String nameFilter = String.format("(%s=%s)", SolrConstants.PROPERTY_CORE_NAME, "mydata");
ServiceReference[] solrCoreRefs = bc.getServiceReferences(
SolrCore.class.getName(), nameFilter);
- //TODO: check that != null AND not empty!
- //now we have all References to CoreContainer with a SolrCore "mydata"
- //let get the one with the highest service.ranking
- Arrays.sort(solrCoreRefs,ServiceReferenceRankingComparator.INSTANCE);
-
- //now get the SolrCore and create the SolrServer
- SolrCore core = (SolrCore)bc.getService(solrCoreRefs[0]);
- //core.getCoreDescriptor() might be null if SolrCore is not
- //registered with a CoreContainer
+
+ // TODO: check that != null AND not empty!
+ // Now we have all References to CoreContainer with a SolrCore "mydata"
+ // let get the one with the highest service.ranking
+ Arrays.sort(solrCoreRefs, ServiceReferenceRankingComparator.INSTANCE);
+
+ // Now get the SolrCore and create the SolrServer
+ SolrCore core = (SolrCore) bc.getService(solrCoreRefs[0]);
+
+ // core.getCoreDescriptor() might be null if SolrCore is not
+ // registered with a CoreContainer
SolrServer server = new EmbeddedSolrServer(
- core.getCoreDescriptor().getCoreContainer(),
- "mydata");
+ core.getCoreDescriptor().getCoreContainer(), "mydata");
+
#### Tracking Solr Indexes
The above examples do a lookup at a single point in time. However because OSGi is an dynamic environment where services can come the go at every time in most cases users might rather want to track services. To do this OSGi provides the ServiceTracker utility.
-To ease the tracking of SolrServers the "org.apache.stanbol.commons.solr.core" bundle provides the RegisteredSolrServerTracker. The following examples show how to create a Managed SolrIndex and than track the SolrServer
+To ease the tracking of SolrServers the "org.apache.stanbol.commons.solr.core" bundle provides the RegisteredSolrServerTracker. The following examples show how to create a Managed SolrIndex and than track the SolrServer.
-First during the activation we need to check if "mydata" is already create and create it if not. Than we can start tracking the index.
+First during the activation we need to check if "mydata" is already created and create it if not. Than we can start tracking the index:
BundleContext bc;
+ // The ManagedSolrServer instance can be looked up manually using a service
+ // reference or using declarative services / SCR injection
IndexMetadata metadata = managedServer.getIndexMetadata("mydata");
- if(metadata == null){ //no index with that name
- //Asynchronously init the index as soon as the solrindex archvive is available
- metadata = managedServer.createSolrIndex("mydata", "mydata.solrindex.zip",null);
+ if (metadata == null) {
+ // No index with that name:
+ // Asynchronously init the index as soon as the solrindex archive is available
+ metadata = managedServer.createSolrIndex("mydata", "mydata.solrindex.zip", null);
}
RegisteredSolrServerTracker indexTracker =
new RegisteredSolrServerTracker(bc, metadata.getIndexReference());
- //do not forget to close the tracker while deactivating
+
+ // Do not forget to close the tracker while deactivating
indexTracker.open();
Now every time we need the SolrServer we can retrieve it from the indexTracker
- private SolrServer getServer(){
+ private SolrServer getServer() {
SolrServer server = indexTracker.getService();
- if(server == null){ //report the missing server
+ if(server == null) {
+ // Report the missing server
throw new IllegalStateException("Server 'mydata' not active");
} else {
return server;
@@ -266,9 +281,11 @@ Now every time we need the SolrServer we
The RegisteredSolrServerTracker does take "service.ranking" into account. So if there are more Services available that match the passed IndexReference those methods will always return the one with the highest "service.ranking". In case arrays are returned such arrays are sorted accordingly.
+
### RESTful API
-This describes how to publish the RESTful API of CoreContainer registered as OSGi services on the OSGi HttpService. The functionality described in this section is provided by the "org.apache.stanbol.commons.solr.web" artifact.
+The following describes how to publish the RESTful API of CoreContainer registered as OSGi services on the OSGi HttpService. The functionality described in this section is provided by the "org.apache.stanbol.commons.solr.web" artifact.
+
#### SolrServerPublishingComponent
@@ -280,6 +297,7 @@ If two CoreContainers with the same {ser
The root-prefix ("/solr" by default) can be configured by setting the "org.apache.stanbol.commons.solr.web.dispatchfilter.prefix" property.
+
#### SolrDispatchFilterComponent
This Component provides the same functionality as the SolrServerPublishingComponent, but can be configured specifically for a CoreContainer. It is intended to be used if one wants to publish the RESTful API of a specific CoreContainer under a specific location. To deactivate the publishing of the same core on the SolrServerPublishingComponent users need to set the "org.apache.solr.core.CoreContainer.publishREST" to false.