This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-discovery-api.git
commit a052911e6eeb27f3054a1c8e25c7e7858ae333c8 Author: Carsten Ziegeler <cziege...@apache.org> AuthorDate: Sun May 5 10:35:09 2013 +0000 Move discovery to bundles section git-svn-id: https://svn.apache.org/repos/asf/sling/trunk@1479281 13f79535-47bb-0310-9956-ffa450edef68 --- pom.xml | 86 +++++ .../org/apache/sling/discovery/ClusterView.java | 57 +++ .../apache/sling/discovery/DiscoveryService.java | 50 +++ .../sling/discovery/InstanceDescription.java | 106 ++++++ .../org/apache/sling/discovery/InstanceFilter.java | 37 ++ .../apache/sling/discovery/PropertyProvider.java | 55 +++ .../org/apache/sling/discovery/TopologyEvent.java | 158 +++++++++ .../sling/discovery/TopologyEventListener.java | 59 ++++ .../org/apache/sling/discovery/TopologyView.java | 71 ++++ .../discovery/impl/NoClusterDiscoveryService.java | 392 +++++++++++++++++++++ .../discovery/impl/StandardPropertyProvider.java | 219 ++++++++++++ .../org/apache/sling/discovery/package-info.java | 30 ++ 12 files changed, 1320 insertions(+) diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..f30d328 --- /dev/null +++ b/pom.xml @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.apache.sling</groupId> + <artifactId>sling</artifactId> + <version>15</version> + <relativePath>../../../parent/pom.xml</relativePath> + </parent> + + <artifactId>org.apache.sling.discovery.api</artifactId> + <packaging>bundle</packaging> + <version>0.1.0-SNAPSHOT</version> + + <name>Apache Sling Discovery API</name> + <description> + Support for topology discovery of instances. + </description> + + <scm> + <connection>scm:svn:http://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/discovery/api</connection> + <developerConnection>scm:svn:https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/discovery/api</developerConnection> + <url>http://svn.apache.org/viewvc/sling/trunk/contrib/extensions/discovery/api</url> + </scm> + + <build> + <plugins> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-scr-plugin</artifactId> + </plugin> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <extensions>true</extensions> + </plugin> + </plugins> + </build> + <dependencies> + <dependency> + <groupId>org.apache.felix</groupId> + <artifactId>org.apache.felix.scr.annotations</artifactId> + </dependency> + <dependency> + <groupId>biz.aQute</groupId> + <artifactId>bndlib</artifactId> + </dependency> + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-api</artifactId> + </dependency> + <dependency> + <groupId>org.osgi</groupId> + <artifactId>org.osgi.core</artifactId> + </dependency> + <dependency> + <groupId>org.osgi</groupId> + <artifactId>org.osgi.compendium</artifactId> + </dependency> + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.settings</artifactId> + <version>1.1.0</version> + <scope>provided</scope> + </dependency> + </dependencies> +</project> diff --git a/src/main/java/org/apache/sling/discovery/ClusterView.java b/src/main/java/org/apache/sling/discovery/ClusterView.java new file mode 100644 index 0000000..64744a1 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/ClusterView.java @@ -0,0 +1,57 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +import java.util.List; + +/** + * A ClusterView represents the instances of a cluster that are + * up and running and that all can see each other at a certain point in time. + * <p> + * A ClusterView can also consist of just one single instance. + */ +public interface ClusterView { + + /** + * Returns an id of this cluster view + * @return an id of this cluster view + */ + String getId(); + + /** + * Provides the list of InstanceDescriptions with a stable ordering. + * <p> + * Stable ordering implies that unless an instance leaves the cluster + * (due to shutdown/crash/network problems) the instance keeps the + * relative position in the list. + * @return the list of InstanceDescriptions (with a stable ordering) + */ + List<InstanceDescription> getInstances(); + + /** + * Provides the InstanceDescription belonging to the leader instance. + * <p> + * Every ClusterView is guaranteed to have one and only one leader. + * <p> + * The leader is stable: once a leader is elected it stays leader + * unless it leaves the cluster (due to shutdown/crash/network problems) + * @return the InstanceDescription belonging to the leader instance + */ + InstanceDescription getLeader(); +} diff --git a/src/main/java/org/apache/sling/discovery/DiscoveryService.java b/src/main/java/org/apache/sling/discovery/DiscoveryService.java new file mode 100644 index 0000000..3477650 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/DiscoveryService.java @@ -0,0 +1,50 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +/** + * The discovery service can be used to get the current topology view. + * <p> + * The discovery service is in charge of managing live instances that + * have announced themselves as being part of a topology view. The exact + * details of how this announcement occurs is implementation dependent. + */ +public interface DiscoveryService { + + /** + * Returns the topology that was last discovered by this service. + * <p> + * If for some reason the service is currently not able to do topology discovery + * it will return the last valid topology marked with <code>false</code> in the call + * to <codeTopologyView.isCurrent()</code>. This is also true if the service + * has noticed a potential change in the topology and is in the process of + * settling the change in the topology (eg with peers, ie voting). + * <p> + * Note that this call is synchronized with <code>TopologyEventListener.handleTopologyEvent()</code> + * calls: ie if calls to <code>TopologyEventListener.handleTopologyEvent()</code> are currently + * ongoing, then the call to this method will block until all <code>TopologyEventListener</code>s + * have been called. Be careful not to cause deadlock situations. + * <p> + * @return the topology that was last discovered by this service. This will never + * be null (ie even if a change in the topology is ongoing at the moment or the + * cluster consists only of the local instance). + */ + TopologyView getTopology(); + +} diff --git a/src/main/java/org/apache/sling/discovery/InstanceDescription.java b/src/main/java/org/apache/sling/discovery/InstanceDescription.java new file mode 100644 index 0000000..0c714a3 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/InstanceDescription.java @@ -0,0 +1,106 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +import java.util.Map; + +/** + * An InstanceDescription represents and contains information about an + * instance that is part of a TopologyView. + * <p> + * Note that all methods are idempotent - they always return the same values + * on subsequent calls. Rather, on any change new InstanceDescriptions are created. + * + * + * @see TopologyView + */ +public interface InstanceDescription { + + /** + * Property containing a name for the instance. + * The instance should provide this property. + */ + String PROPERTY_NAME = "org.apache.sling.instance.name"; + + /** + * Property containing a description for the instance. + * The instance should provide this property. + */ + String PROPERTY_DESCRIPTION = "org.apache.sling.instance.name"; + + /** + * Property containing endpoints to connect to the instance. The + * value is a comma separated list. + * The instance should provide this property. + */ + String PROPERTY_ENDPOINTS = "org.apache.sling.instance.endpoints"; + + /** + * Returns the ClusterView of which this instance is part of. + * <p> + * Every instance is part of a ClusterView even if it is standalone. + * @return the ClusterView + */ + ClusterView getClusterView(); + + /** + * If an instance is part of a cluster, it can potentially be a leader of that cluster - + * this information is queried here. + * <p> + * If an instance is not part of a cluster, this method returns true. + * <p> + * Only one instance of a cluster is guaranteed to be the leader at any time. + * This guarantee is provided by this service. + * If the leader goes down, the service elects a new leader and announces it to + * TopologyEventListener listeners. + * @return true if this instance is the - only - leader in this cluster, + * false if it is one of the slaves, or true if it is not at all part of a cluster + */ + boolean isLeader(); + + /** + * Determines whether this InstanceDescription is representing the local instance. + * @return whether this InstanceDescription is representing the local instance. + */ + boolean isLocal(); + + /** + * The identifier of the running Sling instance. + */ + String getSlingId(); + + /** + * Returns the value of a particular property. + * <p> + * Note that there are no hard guarantees or requirements as to how quickly + * a property is available once it is set on a distant instance. + * @param name The property name + * @return The value of the property or <code>null</code> + * @see DiscoveryService#setProperty(String, String) + */ + String getProperty(final String name); + + /** + * Returns a Map containing all properties of this instance. + * This method always returns a map, it might be empty. The returned map + * is not modifiable. + * @return a Map containing all properties of this instance + */ + Map<String,String> getProperties(); +} diff --git a/src/main/java/org/apache/sling/discovery/InstanceFilter.java b/src/main/java/org/apache/sling/discovery/InstanceFilter.java new file mode 100644 index 0000000..a6e5a51 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/InstanceFilter.java @@ -0,0 +1,37 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +/** + * Used to filter InstanceDescriptions in a TopologyView. + * <p> + * @see DiscoveryService#findInstances(InstanceFilter) + */ +public interface InstanceFilter { + + /** + * Returns true if this InstanceFilter selects the given InstanceDescription. + * <p> + * @param instance the InstanceDescription for which to decide if this + * InstanceFilter accepts it or not. + * @return true if this InstanceFilter selects the given InstanceDescription + */ + boolean accept(InstanceDescription instance); + +} diff --git a/src/main/java/org/apache/sling/discovery/PropertyProvider.java b/src/main/java/org/apache/sling/discovery/PropertyProvider.java new file mode 100644 index 0000000..2fa21f8 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/PropertyProvider.java @@ -0,0 +1,55 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + + +/** + * The <code>PropertyProvider</code> service interface may be implemented by + * components that wish to define properties on the local instance which then + * are broadcast to the <code>TopologyView</code> instances. + * <p> + * The provided properties are registered with the {@link #PROPERTY_PROPERTIES} + * service property. + * If the set of provided properties changes or one of the provided values + * change, the service registration of the provider should be updated. + * This avoids periodic polling for changes. + */ +public interface PropertyProvider { + + /** + * The name of the service registration property containing the names + * of the properties provided by this provider. + * The value is either a string or an array of strings. + * A property name must only contain alphanumeric characters plus <code>.</code>, + * <code>_</code>, <code>-</code>. + */ + String PROPERTY_PROPERTIES = "instance.properties"; + + /** + * Retrieves a property that is subsequently set on the local instance + * and broadcast to the <code>TopologyView</code> instances. + * <p> + * These properties are non-persistent and disappear after the local instance goes down. + * + * @return The value of the property or <code>null</code>. If the property + * value can't be provided or if the provider does not support this + * property, it must return <code>null</code>. + */ + String getProperty(final String name); +} diff --git a/src/main/java/org/apache/sling/discovery/TopologyEvent.java b/src/main/java/org/apache/sling/discovery/TopologyEvent.java new file mode 100644 index 0000000..65dc13f --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/TopologyEvent.java @@ -0,0 +1,158 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +/** + * A topology event is sent whenever a change in the topology occurs. + * + * This event object might be extended in the future with new event types and + * methods. + * + * @see TopologyEventListener + */ +public class TopologyEvent { + + public static enum Type { + /** + * Informs the service about the initial topology state - this is only + * sent once at bind-time and is the first one a TopologyEventListener + * receives (after the implementation bundle was activated). + */ + TOPOLOGY_INIT, + + /** + * Informs the service about the fact that a state change was detected in + * the topology/cluster and that the new state is in the process of + * being discovered. Once the discovery is finished, a TOPOLOGY_CHANGED + * is sent with the new topology view. + * <p> + * An implementation must always send a TOPOLOGY_CHANGING before a + * TOPOLOGY_CHANGED. + */ + TOPOLOGY_CHANGING, + + /** + * Informs the service about a state change in the topology. + * <p> + * A state change includes: + * <ul> + * <li>A joining or leaving instance</li> + * <li>A restart of an instance - or more precisely: when the + * corresponding implementation bundle is deactivated/activated</li> + * <li>A cluster structure - either its members or the cluster + * view id - changed. The cluster view id changes when an instance joins, + * leaves or was restarted (its bundle deactivated/activated)</li> + * </ul> + * <p> + * Note that a TOPOLOGY_CHANGED can also include changes in the + * properties! + */ + TOPOLOGY_CHANGED, + + /** + * One or many properties have been changed on an instance which is part + * of the topology. + * <p> + * This event is sent when otherwise the topology remains identical. + */ + PROPERTIES_CHANGED + + } + + private final Type type; + private final TopologyView oldView; + private final TopologyView newView; + + public TopologyEvent(final Type type, final TopologyView oldView, + final TopologyView newView) { + if (type == null) { + throw new IllegalArgumentException("type must not be null"); + } + + if (type == Type.TOPOLOGY_INIT) { + // then oldView is null + if (oldView != null) { + throw new IllegalArgumentException("oldView must be null"); + } + // and newView must be not null + if (newView == null) { + throw new IllegalArgumentException("newView must not be null"); + } + } else if (type == Type.TOPOLOGY_CHANGING) { + // then newView is null + if (newView != null) { + throw new IllegalArgumentException("newView must be null"); + } + // and oldView must not be null + if (oldView == null) { + throw new IllegalArgumentException("oldView must not be null"); + } + } else { + // in all other cases both oldView and newView must not be null + if (oldView == null) { + throw new IllegalArgumentException("oldView must not be null"); + } + if (newView == null) { + throw new IllegalArgumentException("newView must not be null"); + } + } + this.type = type; + this.oldView = oldView; + this.newView = newView; + } + + /** + * Returns the type of this event + * + * @return the type of this event + */ + public Type getType() { + return type; + } + + /** + * Returns the view which was valid up until now. + * <p> + * This is null in case of <code>TOPOLOGY_INIT</code> + * + * @return the view which was valid up until now, or null in case of a fresh + * instance start + */ + public TopologyView getOldView() { + return oldView; + } + + /** + * Returns the view which is currently (i.e. newly) valid. + * <p> + * This is null in case of <code>TOPOLOGY_CHANGING</code> + * + * @return the view which is currently valid, or null in case of + * <code>TOPOLOGY_CHANGING</code> + */ + public TopologyView getNewView() { + return newView; + } + + @Override + public String toString() { + return "TopologyEvent [type=" + type + ", oldView=" + oldView + + ", newView=" + newView + "]"; + } +} diff --git a/src/main/java/org/apache/sling/discovery/TopologyEventListener.java b/src/main/java/org/apache/sling/discovery/TopologyEventListener.java new file mode 100644 index 0000000..aed95c6 --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/TopologyEventListener.java @@ -0,0 +1,59 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +/** + * The <code>TopologyEventListener</code> service interface may be implemented by + * components interested in being made aware of changes in the topology. + * <p> + * Upon registration and whenever changes in the topology occur, this + * service is informed. + */ +public interface TopologyEventListener { + + /** + * Inform the service about an event in the topology - or in the discovery + * of the topology. + * <p> + * The <code>TopologyEvent</code> contains details about what changed. + * The supported event types are: + * <ul> + * <li><code>TOPOLOGY_INIT</code> sent when the <code>TopologyEventListener</code> + * was first bound to the discovery service - represents the initial state + * of the topology at that time.</li> + * <li><code>TOPOLOGY_CHANGING</code> sent when the discovery service + * discovered a change in the topology and has started to settle the change. + * This event is sent before <code>TOPOLOGY_CHANGED</code> but is optional</li> + * <li><code>TOPOLOGY_CHANGED</code> sent when the discovery service + * discovered a change in the topology and has settled it.</li> + * <li><code>PROPERTIES_CHANGED</code> sent when the one or many properties + * have changed in an instance in the current topology</li> + * </ul> + * A note on instance restarts: it is currently not a requirement on the + * discovery service to send a TopologyEvent should an instance restart + * occur rapidly (ie within the change detection timeout). A TopologyEvent + * is only sent if the number of instances or any property changes. + * Should there be a requirement to detect a restart in a guaranteed fashion, + * it is always possible to set a particular property (using the PropertyProvider) + * to the instance start time and have others detect a change in that property. + * @param event The topology event + */ + void handleTopologyEvent(TopologyEvent event); + +} diff --git a/src/main/java/org/apache/sling/discovery/TopologyView.java b/src/main/java/org/apache/sling/discovery/TopologyView.java new file mode 100644 index 0000000..cc143ce --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/TopologyView.java @@ -0,0 +1,71 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery; + +import java.util.Set; + +/** + * A topology view is a cross-cluster list of instances and clusters + * that have announced themselves with the DiscoveryService. + * + */ +public interface TopologyView { + + /** + * Checks if this TopologyView is currently valid - or if the + * service knows of a topology change just going on (or another + * uncertainty about the topology such as IOException etc) + * @return true if this TopologyView is currently valid, false + * if the service knows of a topology change just going on (or + * another issue with discovery like IOException etc) + */ + boolean isCurrent(); + + /** + * Provides the InstanceDescription belonging to <b>this</b> instance. + * @return the InstanceDescription belonging to <b>this</b> instance + */ + InstanceDescription getLocalInstance(); + + /** + * Provides the set of InstanceDescriptions in the entire topology, + * without any particular order + * @return the set of InstanceDescriptions in the entire topology, + * without any particular order + */ + Set<InstanceDescription> getInstances(); + + /** + * Searches through this topology and picks those accepted by the provided + * <code>InstanceFilter</code> - and returns them without any particular order + * @param filter the filter to use + * @return the set of InstanceDescriptions which were accepted by the InstanceFilter, + * without any particular order + */ + Set<InstanceDescription> findInstances(InstanceFilter filter); + + /** + * Provides the collection of ClusterViews. + * <p> + * Note that all InstanceDescriptions belong to exactly one ClusterView - + * including InstanceDescriptions that form "a cluster of 1" + * @return the set of ClusterViews, without any particular order + */ + Set<ClusterView> getClusterViews(); +} diff --git a/src/main/java/org/apache/sling/discovery/impl/NoClusterDiscoveryService.java b/src/main/java/org/apache/sling/discovery/impl/NoClusterDiscoveryService.java new file mode 100644 index 0000000..cfb3c6b --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/impl/NoClusterDiscoveryService.java @@ -0,0 +1,392 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery.impl; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Collection; +import java.util.Collections; +import java.util.HashMap; +import java.util.HashSet; +import java.util.Iterator; +import java.util.LinkedList; +import java.util.List; +import java.util.Map; +import java.util.Set; + +import org.apache.felix.scr.annotations.Activate; +import org.apache.felix.scr.annotations.Component; +import org.apache.felix.scr.annotations.ConfigurationPolicy; +import org.apache.felix.scr.annotations.Deactivate; +import org.apache.felix.scr.annotations.Reference; +import org.apache.felix.scr.annotations.ReferenceCardinality; +import org.apache.felix.scr.annotations.ReferencePolicy; +import org.apache.felix.scr.annotations.Service; +import org.apache.sling.discovery.ClusterView; +import org.apache.sling.discovery.DiscoveryService; +import org.apache.sling.discovery.InstanceDescription; +import org.apache.sling.discovery.InstanceFilter; +import org.apache.sling.discovery.PropertyProvider; +import org.apache.sling.discovery.TopologyEvent; +import org.apache.sling.discovery.TopologyEvent.Type; +import org.apache.sling.discovery.TopologyEventListener; +import org.apache.sling.discovery.TopologyView; +import org.apache.sling.settings.SlingSettingsService; +import org.osgi.framework.Constants; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * This is a simple implementation of the discovery service + * which can be used for a cluster less installation (= single instance). + * It is disabled by default and can be enabled through a OSGi configuration. + */ +@Component(policy = ConfigurationPolicy.REQUIRE, immediate=true) +@Service(value = {DiscoveryService.class}) +public class NoClusterDiscoveryService implements DiscoveryService { + + /** The logger. */ + private final Logger logger = LoggerFactory.getLogger(this.getClass()); + + /** + * Sling settings service to get the Sling ID and run modes. + */ + @Reference + private SlingSettingsService settingsService; + + /** + * All topology event listeners. + */ + @Reference(cardinality = ReferenceCardinality.OPTIONAL_MULTIPLE, policy = ReferencePolicy.DYNAMIC) + private TopologyEventListener[] listeners = new TopologyEventListener[0]; + + /** + * All property providers. + */ + @Reference(cardinality = ReferenceCardinality.OPTIONAL_MULTIPLE, policy = ReferencePolicy.DYNAMIC, + referenceInterface=PropertyProvider.class, updated="updatedPropertyProvider") + private List<ProviderInfo> providerInfos = new ArrayList<ProviderInfo>(); + + /** + * Special lock object to sync data structure access + */ + private final Object lock = new Object(); + + /** + * The current topology view. + */ + private TopologyView topologyView; + + private Map<String, String> cachedProperties = new HashMap<String, String>(); + + /** + * Activate this service + * Create a new description. + */ + @Activate + protected void activate() { + logger.debug("NoClusterDiscoveryService started."); + final InstanceDescription myDescription = new InstanceDescription() { + + public boolean isLocal() { + return true; + } + + public boolean isLeader() { + return true; + } + + public String getSlingId() { + return settingsService.getSlingId(); + } + + public String getProperty(final String name) { + synchronized(lock) { + return cachedProperties.get(name); + } + } + + public Map<String, String> getProperties() { + synchronized(lock) { + return Collections.unmodifiableMap(cachedProperties); + } + } + + public ClusterView getClusterView() { + final Collection<ClusterView> clusters = topologyView.getClusterViews(); + if (clusters==null || clusters.size()==0) { + return null; + } + return clusters.iterator().next(); + } + }; + final Set<InstanceDescription> instances = new HashSet<InstanceDescription>(); + instances.add(myDescription); + + final TopologyEventListener[] registeredServices; + synchronized ( lock ) { + registeredServices = this.listeners; + final ClusterView clusterView = new ClusterView() { + + public InstanceDescription getLeader() { + return myDescription; + } + + public List<InstanceDescription> getInstances() { + return new LinkedList<InstanceDescription>(instances); + } + + public String getId() { + return "0"; + } + }; + this.topologyView = new TopologyView() { + + public InstanceDescription getLocalInstance() { + return myDescription; + } + + public boolean isCurrent() { + return true; + } + + public Set<InstanceDescription> getInstances() { + return instances; + } + + public Set<InstanceDescription> findInstances(InstanceFilter picker) { + Set<InstanceDescription> result = new HashSet<InstanceDescription>(); + for (Iterator<InstanceDescription> it = getTopology().getInstances().iterator(); it.hasNext();) { + InstanceDescription instance = it.next(); + if (picker.accept(instance)) { + result.add(instance); + } + } + return result; + } + + public Set<ClusterView> getClusterViews() { + Set<ClusterView> clusters = new HashSet<ClusterView>(); + clusters.add(clusterView); + return clusters; + } + + }; + } + for(final TopologyEventListener da: registeredServices) { + da.handleTopologyEvent(new TopologyEvent(Type.TOPOLOGY_INIT, null, topologyView)); + } + } + + /** + * Deactivate this service. + */ + @Deactivate + protected void deactivate() { + logger.debug("NoClusterDiscoveryService stopped."); + this.topologyView = null; + } + + /** + * Bind a new property provider. + */ + @SuppressWarnings("unused") + private void bindPropertyProvider(final PropertyProvider propertyProvider, final Map<String, Object> props) { + logger.debug("bindPropertyProvider: Binding PropertyProvider {}", propertyProvider); + + final TopologyEventListener[] awares; + synchronized (lock) { + final ProviderInfo info = new ProviderInfo(propertyProvider, props); + this.providerInfos.add(info); + Collections.sort(this.providerInfos); + this.updatePropertiesCache(); + if ( this.topologyView == null ) { + awares = null; + } else { + awares = this.listeners; + } + } + if ( awares != null ) { + for(final TopologyEventListener da : awares) { + da.handleTopologyEvent(new TopologyEvent(Type.PROPERTIES_CHANGED, this.topologyView, this.topologyView)); + } + } + } + + /** + * Update a property provider. + */ + @SuppressWarnings("unused") + private void updatedPropertyProvider(final PropertyProvider propertyProvider, final Map<String, Object> props) { + logger.debug("bindPropertyProvider: Updating PropertyProvider {}", propertyProvider); + + this.unbindPropertyProvider(propertyProvider, props, false); + this.bindPropertyProvider(propertyProvider, props); + } + + /** + * Unbind a property provider + */ + @SuppressWarnings("unused") + private void unbindPropertyProvider(final PropertyProvider propertyProvider, final Map<String, Object> props) { + this.unbindPropertyProvider(propertyProvider, props, true); + } + + /** + * Unbind a property provider + */ + @SuppressWarnings("unused") + private void unbindPropertyProvider(final PropertyProvider propertyProvider, + final Map<String, Object> props, + final boolean inform) { + logger.debug("unbindPropertyProvider: Releasing PropertyProvider {}", propertyProvider); + + final TopologyEventListener[] awares; + synchronized (lock) { + final ProviderInfo info = new ProviderInfo(propertyProvider, props); + this.providerInfos.remove(info); + this.updatePropertiesCache(); + if ( this.topologyView == null ) { + awares = null; + } else { + awares = this.listeners; + } + } + if ( inform && awares != null ) { + for(final TopologyEventListener da : awares) { + da.handleTopologyEvent(new TopologyEvent(Type.PROPERTIES_CHANGED, this.topologyView, this.topologyView)); + } + } + } + + private void updatePropertiesCache() { + final Map<String, String> newProps = new HashMap<String, String>(); + for(final ProviderInfo info : this.providerInfos) { + newProps.putAll(info.properties); + } + this.cachedProperties = newProps; + if ( this.logger.isDebugEnabled() ) { + this.logger.debug("New properties: {}", this.cachedProperties); + } + } + + @SuppressWarnings("unused") + private void bindTopologyEventListener(final TopologyEventListener clusterAware) { + + logger.debug("bindTopologyEventListener: Binding TopologyEventListener {}", clusterAware); + + boolean inform = true; + synchronized (lock) { + List<TopologyEventListener> currentList = new ArrayList<TopologyEventListener>( + Arrays.asList(listeners)); + currentList.add(clusterAware); + this.listeners = currentList.toArray(new TopologyEventListener[currentList.size()]); + if ( this.topologyView == null ) { + inform = false; + } + } + + if ( inform ) { + clusterAware.handleTopologyEvent(new TopologyEvent(Type.TOPOLOGY_INIT, null, topologyView)); + } + } + + @SuppressWarnings("unused") + private void unbindTopologyEventListener(final TopologyEventListener clusterAware) { + + logger.debug("unbindTopologyEventListener: Releasing TopologyEventListener {}", clusterAware); + + synchronized (lock) { + List<TopologyEventListener> currentList = new ArrayList<TopologyEventListener>( + Arrays.asList(listeners)); + currentList.remove(clusterAware); + this.listeners = currentList.toArray(new TopologyEventListener[currentList.size()]); + } + } + + /** + * @see DiscoveryService#getTopology() + */ + public TopologyView getTopology() { + return topologyView; + } + + /** + * Internal class caching some provider infos like service id and ranking. + */ + private final static class ProviderInfo implements Comparable<ProviderInfo> { + + public final PropertyProvider provider; + public final int ranking; + public final long serviceId; + public final Map<String, String> properties = new HashMap<String, String>(); + + public ProviderInfo(final PropertyProvider provider, final Map<String, Object> serviceProps) { + this.provider = provider; + final Object sr = serviceProps.get(Constants.SERVICE_RANKING); + if ( sr == null || !(sr instanceof Integer)) { + this.ranking = 0; + } else { + this.ranking = (Integer)sr; + } + this.serviceId = (Long)serviceProps.get(Constants.SERVICE_ID); + final Object namesObj = serviceProps.get(PropertyProvider.PROPERTY_PROPERTIES); + if ( namesObj instanceof String ) { + final String val = provider.getProperty((String)namesObj); + if ( val != null ) { + this.properties.put((String)namesObj, val); + } + } else if ( namesObj instanceof String[] ) { + for(final String name : (String[])namesObj ) { + final String val = provider.getProperty(name); + if ( val != null ) { + this.properties.put(name, val); + } + } + } + } + + /** + * @see java.lang.Comparable#compareTo(java.lang.Object) + */ + public int compareTo(final ProviderInfo o) { + // Sort by rank in ascending order. + if ( this.ranking < o.ranking ) { + return -1; // lower rank + } else if (this.ranking > o.ranking ) { + return 1; // higher rank + } + // If ranks are equal, then sort by service id in descending order. + return (this.serviceId < o.serviceId) ? 1 : -1; + } + + @Override + public boolean equals(final Object obj) { + if ( obj instanceof ProviderInfo ) { + return ((ProviderInfo)obj).serviceId == this.serviceId; + } + return false; + } + + @Override + public int hashCode() { + return provider.hashCode(); + } + } +} diff --git a/src/main/java/org/apache/sling/discovery/impl/StandardPropertyProvider.java b/src/main/java/org/apache/sling/discovery/impl/StandardPropertyProvider.java new file mode 100644 index 0000000..798ff0a --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/impl/StandardPropertyProvider.java @@ -0,0 +1,219 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.sling.discovery.impl; + +import java.util.ArrayList; +import java.util.Collection; +import java.util.Dictionary; +import java.util.HashMap; +import java.util.Hashtable; +import java.util.List; +import java.util.Map; + +import org.apache.felix.scr.annotations.Activate; +import org.apache.felix.scr.annotations.Component; +import org.apache.felix.scr.annotations.Deactivate; +import org.apache.felix.scr.annotations.Modified; +import org.apache.felix.scr.annotations.Reference; +import org.apache.felix.scr.annotations.ReferenceCardinality; +import org.apache.felix.scr.annotations.ReferencePolicy; +import org.apache.sling.discovery.InstanceDescription; +import org.apache.sling.discovery.PropertyProvider; +import org.osgi.framework.Constants; +import org.osgi.framework.ServiceReference; +import org.osgi.framework.ServiceRegistration; +import org.osgi.service.component.ComponentContext; +import org.osgi.service.http.HttpService; + +/** + * This service provides the standard instance properties (if available) + */ +@Component(immediate=true) +@Reference(referenceInterface=HttpService.class, + cardinality=ReferenceCardinality.OPTIONAL_MULTIPLE, + policy=ReferencePolicy.DYNAMIC) +public class StandardPropertyProvider { + + /** Endpoint service registration property from RFC 189 */ + private static final String REG_PROPERTY_ENDPOINTS = "osgi.http.service.endpoints"; + + private volatile long changeCount; + + private String instanceName; + + private String instanceDescription; + + private ServiceRegistration propagationService; + + private final Map<Long, String[]> endpoints = new HashMap<Long, String[]>(); + + private String endpointString; + + private Dictionary<String, Object> getRegistrationProperties() { + final List<String> names = new ArrayList<String>(); + if ( this.instanceName != null ) { + names.add(InstanceDescription.PROPERTY_NAME); + } + if ( this.instanceDescription != null ) { + names.add(InstanceDescription.PROPERTY_DESCRIPTION); + } + names.add(InstanceDescription.PROPERTY_ENDPOINTS); + + final StringBuilder sb = new StringBuilder(); + boolean first = true; + synchronized ( this.endpoints ) { + for(final String[] points : endpoints.values()) { + for(final String point : points) { + if ( first ) { + first = false; + } else { + sb.append(","); + } + sb.append(point); + } + } + } + this.endpointString = sb.toString(); + + final Dictionary<String, Object> serviceProps = new Hashtable<String, Object>(); + serviceProps.put(PropertyProvider.PROPERTY_PROPERTIES, names.toArray(new String[names.size()])); + // we add a changing property to the service registration + // to make sure a modification event is really sent + synchronized ( this ) { + serviceProps.put("changeCount", this.changeCount++); + } + return serviceProps; + } + + private String getPropertyValue(final ComponentContext bc, final String key) { + Object value = bc.getProperties().get(key); + if ( value == null ) { + value = bc.getBundleContext().getProperty(key); + } + if ( value != null ) { + return value.toString(); + } + return null; + } + + @Activate + protected void activate(final ComponentContext cc) { + this.modified(cc); + } + + @Modified + protected void modified(final ComponentContext cc) { + this.instanceName = this.getPropertyValue(cc, "sling.name"); + this.instanceDescription = this.getPropertyValue(cc, "sling.description"); + + this.propagationService = cc.getBundleContext().registerService(PropertyProvider.class.getName(), + new PropertyProvider() { + + public String getProperty(final String name) { + if ( InstanceDescription.PROPERTY_DESCRIPTION.equals(name) ) { + return instanceDescription; + } + if ( InstanceDescription.PROPERTY_NAME.equals(name) ) { + return instanceName; + } + if ( InstanceDescription.PROPERTY_ENDPOINTS.equals(name) ) { + return endpointString; + } + return null; + } + }, this.getRegistrationProperties()); + } + + @Deactivate + protected void deactivate() { + if ( this.propagationService != null ) { + this.propagationService.unregister(); + this.propagationService = null; + } + } + + /** + * Bind a http service + */ + protected void bindHttpService(final ServiceReference reference) { + final String[] endpointUrls = toStringArray(reference.getProperty(REG_PROPERTY_ENDPOINTS)); + if ( endpointUrls != null ) { + synchronized ( this.endpoints ) { + this.endpoints.put((Long)reference.getProperty(Constants.SERVICE_ID), endpointUrls); + } + if ( this.propagationService != null ) { + this.propagationService.setProperties(this.getRegistrationProperties()); + } + } + } + + /** + * Unbind a http service + */ + protected void unbindHttpService(final ServiceReference reference) { + boolean changed = false; + synchronized ( this.endpoints ) { + if ( this.endpoints.remove(reference.getProperty(Constants.SERVICE_ID)) != null ) { + changed = true; + } + } + if ( changed && this.propagationService != null ) { + this.propagationService.setProperties(this.getRegistrationProperties()); + } + } + + private String[] toStringArray(final Object propValue) { + if (propValue == null) { + // no value at all + return null; + + } else if (propValue instanceof String) { + // single string + return new String[] { (String) propValue }; + + } else if (propValue instanceof String[]) { + // String[] + return (String[]) propValue; + + } else if (propValue.getClass().isArray()) { + // other array + Object[] valueArray = (Object[]) propValue; + List<String> values = new ArrayList<String>(valueArray.length); + for (Object value : valueArray) { + if (value != null) { + values.add(value.toString()); + } + } + return values.toArray(new String[values.size()]); + + } else if (propValue instanceof Collection<?>) { + // collection + Collection<?> valueCollection = (Collection<?>) propValue; + List<String> valueList = new ArrayList<String>(valueCollection.size()); + for (Object value : valueCollection) { + if (value != null) { + valueList.add(value.toString()); + } + } + return valueList.toArray(new String[valueList.size()]); + } + + return null; + } +} diff --git a/src/main/java/org/apache/sling/discovery/package-info.java b/src/main/java/org/apache/sling/discovery/package-info.java new file mode 100644 index 0000000..387bb0f --- /dev/null +++ b/src/main/java/org/apache/sling/discovery/package-info.java @@ -0,0 +1,30 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +/** + * Provides a service to interface which may be implemented by applications + * to get notified on cluster topology changes. + * + * @version 1.0 + */ +@Version("1.0") +package org.apache.sling.discovery; + +import aQute.bnd.annotation.Version; + -- To stop receiving notification emails like this one, please contact "commits@sling.apache.org" <commits@sling.apache.org>.