diff options
Diffstat (limited to 'framework/src/onos/core/api/src/main/java/org/onosproject/net/driver')
19 files changed, 1358 insertions, 0 deletions
diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractBehaviour.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractBehaviour.java new file mode 100644 index 00000000..784e6c55 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractBehaviour.java @@ -0,0 +1,37 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import static com.google.common.base.Preconditions.checkState; + +/** + * Base implementation of device driver behaviour. + */ +public class AbstractBehaviour implements Behaviour { + + private DriverData data; + + @Override + public DriverData data() { + return data; + } + + @Override + public void setData(DriverData data) { + checkState(this.data == null, "Driver data already set"); + this.data = data; + } +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractHandlerBehaviour.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractHandlerBehaviour.java new file mode 100644 index 00000000..66b21ffe --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/AbstractHandlerBehaviour.java @@ -0,0 +1,38 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import static com.google.common.base.Preconditions.checkState; + +/** + * Base implementation of device driver handler behaviour. + */ +public class AbstractHandlerBehaviour + extends AbstractBehaviour implements HandlerBehaviour { + + private DriverHandler handler; + + @Override + public DriverHandler handler() { + return handler; + } + + @Override + public void setHandler(DriverHandler handler) { + checkState(this.handler == null, "Driver handler already set"); + this.handler = handler; + } +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Behaviour.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Behaviour.java new file mode 100644 index 00000000..6e28aa86 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Behaviour.java @@ -0,0 +1,39 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Representation of a facet of device behaviour that can be used to talk about + * a device (in context of {@link DriverData}) or to a device (in context of + * {@link DriverHandler}). + */ +public interface Behaviour { + + /** + * Returns the driver data context. + * + * @return driver data + */ + DriverData data(); + + /** + * Sets the driver data context on this this behaviour should operate. + * + * @param data driver data + */ + void setData(DriverData data); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriver.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriver.java new file mode 100644 index 00000000..b7a9f2b7 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriver.java @@ -0,0 +1,214 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import com.google.common.collect.ImmutableMap; +import com.google.common.collect.Maps; + +import java.util.Map; +import java.util.Objects; +import java.util.Set; + +import static com.google.common.base.MoreObjects.toStringHelper; +import static com.google.common.base.Preconditions.checkArgument; +import static com.google.common.base.Preconditions.checkNotNull; +import static com.google.common.collect.ImmutableMap.copyOf; + +/** + * Default implementation of extensible driver. + */ +public class DefaultDriver implements Driver { + + private final String name; + private final Driver parent; + + private final String manufacturer; + private final String hwVersion; + private final String swVersion; + + private final Map<Class<? extends Behaviour>, Class<? extends Behaviour>> behaviours; + private final Map<String, String> properties; + + /** + * Creates a driver with the specified name. + * + * @param name driver name + * @param parent optional parent driver + * @param manufacturer device manufacturer + * @param hwVersion device hardware version + * @param swVersion device software version + * @param behaviours device behaviour classes + * @param properties properties for configuration of device behaviour classes + */ + public DefaultDriver(String name, Driver parent, String manufacturer, + String hwVersion, String swVersion, + Map<Class<? extends Behaviour>, Class<? extends Behaviour>> behaviours, + Map<String, String> properties) { + this.name = checkNotNull(name, "Name cannot be null"); + this.parent = parent; + this.manufacturer = checkNotNull(manufacturer, "Manufacturer cannot be null"); + this.hwVersion = checkNotNull(hwVersion, "HW version cannot be null"); + this.swVersion = checkNotNull(swVersion, "SW version cannot be null"); + this.behaviours = copyOf(checkNotNull(behaviours, "Behaviours cannot be null")); + this.properties = copyOf(checkNotNull(properties, "Properties cannot be null")); + } + + @Override + public Driver merge(Driver other) { + checkArgument(parent == null || Objects.equals(parent, other.parent()), + "Parent drivers are not the same"); + + // Merge the behaviours. + Map<Class<? extends Behaviour>, Class<? extends Behaviour>> + behaviours = Maps.newHashMap(); + behaviours.putAll(this.behaviours); + other.behaviours().forEach(b -> behaviours.put(b, other.implementation(b))); + + // Merge the properties. + ImmutableMap.Builder<String, String> properties = ImmutableMap.builder(); + properties.putAll(this.properties).putAll(other.properties()); + + return new DefaultDriver(name, other.parent(), manufacturer, hwVersion, swVersion, + ImmutableMap.copyOf(behaviours), properties.build()); + } + + @Override + public String name() { + return name; + } + + @Override + public String manufacturer() { + return manufacturer; + } + + @Override + public String hwVersion() { + return hwVersion; + } + + @Override + public String swVersion() { + return swVersion; + } + + @Override + public Driver parent() { + return parent; + } + + @Override + public Set<Class<? extends Behaviour>> behaviours() { + return behaviours.keySet(); + } + + @Override + public Class<? extends Behaviour> implementation(Class<? extends Behaviour> behaviour) { + return behaviours.get(behaviour); + } + + @Override + public boolean hasBehaviour(Class<? extends Behaviour> behaviourClass) { + return behaviours.containsKey(behaviourClass) || + (parent != null && parent.hasBehaviour(behaviourClass)); + } + + @Override + public <T extends Behaviour> T createBehaviour(DriverData data, + Class<T> behaviourClass) { + T behaviour = createBehaviour(data, null, behaviourClass); + if (behaviour != null) { + return behaviour; + } else if (parent != null) { + return parent.createBehaviour(data, behaviourClass); + } + throw new IllegalArgumentException(behaviourClass.getName() + " not supported"); + } + + @Override + public <T extends Behaviour> T createBehaviour(DriverHandler handler, + Class<T> behaviourClass) { + T behaviour = createBehaviour(handler.data(), handler, behaviourClass); + if (behaviour != null) { + return behaviour; + } else if (parent != null) { + return parent.createBehaviour(handler, behaviourClass); + } + throw new IllegalArgumentException(behaviourClass.getName() + " not supported"); + } + + // Creates an instance of behaviour primed with the specified driver data. + private <T extends Behaviour> T createBehaviour(DriverData data, DriverHandler handler, + Class<T> behaviourClass) { + //checkArgument(handler != null || !HandlerBehaviour.class.isAssignableFrom(behaviourClass), + // "{} is applicable only to handler context", behaviourClass.getName()); + + // Locate the implementation of the requested behaviour. + Class<? extends Behaviour> implementation = behaviours.get(behaviourClass); + if (implementation != null) { + // Create an instance of the behaviour and apply data as its context. + T behaviour = createBehaviour(behaviourClass, implementation); + behaviour.setData(data); + + // If this is a handler behaviour, also apply handler as its context. + if (handler != null) { + ((HandlerBehaviour) behaviour).setHandler(handler); + } + return behaviour; + } + return null; + } + + @SuppressWarnings("unchecked") + private <T extends Behaviour> T createBehaviour(Class<T> behaviourClass, + Class<? extends Behaviour> implementation) { + try { + return (T) implementation.newInstance(); + } catch (InstantiationException | IllegalAccessException e) { + // TODO: add a specific unchecked exception + throw new IllegalArgumentException("Unable to create behaviour", e); + } + } + + @Override + public Set<String> keys() { + return properties.keySet(); + } + + @Override + public String value(String key) { + return properties.get(key); + } + + @Override + public Map<String, String> properties() { + return properties; + } + + @Override + public String toString() { + return toStringHelper(this) + .add("name", name) + .add("parent", parent) + .add("manufacturer", manufacturer) + .add("hwVersion", hwVersion) + .add("swVersion", swVersion) + .add("behaviours", behaviours) + .add("properties", properties) + .toString(); + } + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverData.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverData.java new file mode 100644 index 00000000..76d7932d --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverData.java @@ -0,0 +1,100 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import com.google.common.collect.ImmutableSet; +import org.onosproject.net.DeviceId; +import org.onosproject.net.MutableAnnotations; + +import java.util.HashMap; +import java.util.Map; +import java.util.Set; + +import static com.google.common.base.MoreObjects.toStringHelper; + +/** + * Default implementation of driver data descriptor. + */ +public class DefaultDriverData implements DriverData { + + private final Driver driver; + private final DeviceId deviceId; + private final Map<String, String> properties; + + /** + * Creates new driver data. + * + * @param driver parent driver type + * @param deviceId device identifier + */ + public DefaultDriverData(Driver driver, DeviceId deviceId) { + this.driver = driver; + this.deviceId = deviceId; + this.properties = new HashMap<>(); + } + + @Override + public Driver driver() { + return driver; + } + + @Override + public DeviceId deviceId() { + return deviceId; + } + + @Override + public <T extends Behaviour> T behaviour(Class<T> behaviourClass) { + return driver.createBehaviour(this, behaviourClass); + } + + @Override + public MutableAnnotations set(String key, String value) { + properties.put(key, value); + return this; + } + + @Override + public MutableAnnotations clear(String... keys) { + if (keys.length == 0) { + properties.clear(); + } else { + for (String key : keys) { + properties.remove(key); + } + } + return this; + } + + @Override + public Set<String> keys() { + return ImmutableSet.copyOf(properties.keySet()); + } + + @Override + public String value(String key) { + return properties.get(key); + } + + @Override + public String toString() { + return toStringHelper(this) + .add("type", driver) + .add("properties", properties) + .toString(); + } + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverHandler.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverHandler.java new file mode 100644 index 00000000..28fdb2f3 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverHandler.java @@ -0,0 +1,67 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import org.onlab.osgi.DefaultServiceDirectory; +import org.onlab.osgi.ServiceDirectory; + +import static com.google.common.base.MoreObjects.toStringHelper; + +/** + * Default implementation of driver handler. + */ +public class DefaultDriverHandler implements DriverHandler { + + private final DefaultDriverData data; + + // Reference to service directory to provide run-time context. + protected static ServiceDirectory serviceDirectory = new DefaultServiceDirectory(); + + /** + * Creates new driver handler with the attached driver data. + * + * @param data driver data to attach + */ + public DefaultDriverHandler(DefaultDriverData data) { + this.data = data; + } + + @Override + public Driver driver() { + return data.driver(); + } + + @Override + public DriverData data() { + return data; + } + + @Override + public <T extends Behaviour> T behaviour(Class<T> behaviourClass) { + return data.driver().createBehaviour(this, behaviourClass); + } + + @Override + public <T> T get(Class<T> serviceClass) { + return serviceDirectory.get(serviceClass); + } + + @Override + public String toString() { + return toStringHelper(this).add("data", data).toString(); + } + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProvider.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProvider.java new file mode 100644 index 00000000..b2b5281c --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProvider.java @@ -0,0 +1,86 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import com.google.common.collect.ImmutableSet; +import com.google.common.collect.Maps; + +import java.util.Map; +import java.util.Set; + +import static com.google.common.base.MoreObjects.toStringHelper; + +/** + * Default driver provider implementation. + */ +public class DefaultDriverProvider implements DriverProvider { + + protected final Map<String, Driver> drivers = Maps.newConcurrentMap(); + + @Override + public Set<Driver> getDrivers() { + return ImmutableSet.copyOf(drivers.values()); + } + + /** + * Adds the specified drivers to the provider. + * + * @param drivers drivers to be added + */ + public void addDrivers(Set<Driver> drivers) { + drivers.forEach(this::addDriver); + } + + /** + * Adds the specified driver to the provider. + * + * @param driver driver to be provided + */ + public void addDriver(Driver driver) { + Driver ddc = drivers.get(driver.name()); + if (ddc == null) { + // If we don't have the driver yet, just use the new one. + drivers.put(driver.name(), driver); + } else { + // Otherwise merge the existing driver with the new one and rebind. + drivers.put(driver.name(), ddc.merge(driver)); + } + } + + /** + * Removes the specified drivers from the provider. + * + * @param drivers drivers to be removed + */ + public void removeDrivers(Set<Driver> drivers) { + drivers.forEach(this::removeDriver); + } + + /** + * Removes the specified driver from the provider. + * + * @param driver driver to be removed + */ + public void removeDriver(Driver driver) { + // TODO: make selective if possible + drivers.remove(driver.name()); + } + + @Override + public String toString() { + return toStringHelper(this).add("drivers", drivers).toString(); + } +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProviderService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProviderService.java new file mode 100644 index 00000000..153c7c56 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DefaultDriverProviderService.java @@ -0,0 +1,23 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Service representing availability of default drivers. + */ +public interface DefaultDriverProviderService { +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Driver.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Driver.java new file mode 100644 index 00000000..50611b14 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/Driver.java @@ -0,0 +1,132 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import org.onosproject.net.Annotations; + +import java.util.Map; +import java.util.Set; + +/** + * Representation of a specific family of device drivers. Behaviour configuration + * data is stored using {@link org.onosproject.net.Annotations}. + */ +public interface Driver extends Annotations { + + /** + * Returns the driver name. This is expected to be a reverse-DNS, + * Java package-like name. + * + * @return driver name + */ + String name(); + + /** + * Returns the parent driver from which this driver inherits behaviours + * and properties. + * + * @return parent driver; null if driver has no parent + */ + Driver parent(); + + /** + * Returns the device manufacturer name. + * + * @return manufacturer name + */ + String manufacturer(); + + /** + * Returns the device hardware version. + * + * @return hardware version + */ + String hwVersion(); + + /** + * Returns the device software version. + * + * @return software version + */ + String swVersion(); + + /** + * Returns the set of behaviours supported by this driver. + * It reflects behaviours of only this driver and not its parent. + * + * @return set of device driver behaviours + */ + Set<Class<? extends Behaviour>> behaviours(); + + /** + * Returns the implementation class for the specified behaviour. + * It reflects behaviours of only this driver and not its parent. + * + * @param behaviour behaviour interface + * @return implementation class + */ + Class<? extends Behaviour> implementation(Class<? extends Behaviour> behaviour); + + /** + * Indicates whether or not the driver, or any of its parents, support + * the specified class of behaviour. It + * + * @param behaviourClass behaviour class + * @return true if behaviour is supported + */ + boolean hasBehaviour(Class<? extends Behaviour> behaviourClass); + + /** + * Creates an instance of behaviour primed with the specified driver data. + * If the current driver does not support the specified behaviour and the + * driver has parent, the request is delegated to the parent driver. + * + * @param data driver data context + * @param behaviourClass driver behaviour class + * @param <T> type of behaviour + * @return behaviour instance + */ + <T extends Behaviour> T createBehaviour(DriverData data, Class<T> behaviourClass); + + /** + * Creates an instance of behaviour primed with the specified driver data. + * If the current driver does not support the specified behaviour and the + * driver has parent, the request is delegated to the parent driver. + * + * @param handler driver handler context + * @param behaviourClass driver behaviour class + * @param <T> type of behaviour + * @return behaviour instance + */ + <T extends Behaviour> T createBehaviour(DriverHandler handler, Class<T> behaviourClass); + + /** + * Returns the set of annotations as map of key/value properties. + * + * @return map of properties + */ + Map<String, String> properties(); + + /** + * Merges the specified driver behaviours and properties into this one, + * giving preference to the other driver when dealing with conflicts. + * + * @param other other driver + * @return merged driver + */ + Driver merge(Driver other); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverAdminService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverAdminService.java new file mode 100644 index 00000000..e7fa1385 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverAdminService.java @@ -0,0 +1,46 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import java.util.Set; + +/** + * Service for managing drivers and driver behaviour implementations. + */ +public interface DriverAdminService extends DriverService { + + /** + * Returns the set of driver providers currently registered. + * + * @return registered driver providers + */ + Set<DriverProvider> getProviders(); + + /** + * Registers the specified driver provider. + * + * @param provider driver provider to register + */ + void registerProvider(DriverProvider provider); + + /** + * Unregisters the specified driver provider. + * + * @param provider driver provider to unregister + */ + void unregisterProvider(DriverProvider provider); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverConnect.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverConnect.java new file mode 100644 index 00000000..1d510913 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverConnect.java @@ -0,0 +1,36 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Abstraction of handler behaviour used to set-up and tear-down driver + * connection with a device. + */ +public interface DriverConnect extends HandlerBehaviour { + + /** + * Connects to the device. + * + * @param credentials optional login credentials in string form + */ + void connect(String... credentials); + + /** + * Disconnects from the device. + */ + void disconnect(); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverData.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverData.java new file mode 100644 index 00000000..1d66ea9a --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverData.java @@ -0,0 +1,50 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import org.onosproject.net.DeviceId; +import org.onosproject.net.MutableAnnotations; + +/** + * Container for data about a device. Data is stored using + * {@link org.onosproject.net.MutableAnnotations}. + */ +public interface DriverData extends MutableAnnotations { + + /** + * Returns the parent device driver. + * + * @return device driver + */ + Driver driver(); + + /** + * Returns the device identifier. + * + * @return device identifier + */ + DeviceId deviceId(); + + /** + * Returns the specified facet of behaviour to access the device data. + * + * @param behaviourClass behaviour class + * @param <T> type of behaviour + * @return requested behaviour or null if not supported + */ + <T extends Behaviour> T behaviour(Class<T> behaviourClass); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverHandler.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverHandler.java new file mode 100644 index 00000000..202708ba --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverHandler.java @@ -0,0 +1,57 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Representation of context for interacting with a device. + */ +public interface DriverHandler { + + /** + * Returns the parent device driver. + * + * @return device driver + */ + Driver driver(); + + /** + * Returns the device driver data. + * + * @return device driver data + */ + DriverData data(); + + /** + * Returns the specified facet of behaviour to interact with the device. + * + * @param behaviourClass behaviour class + * @param <T> type of behaviour + * @return behaviour + */ + <T extends Behaviour> T behaviour(Class<T> behaviourClass); + + /** + * Returns the reference to the implementation of the specified service. + * Provides access to run-time context. + * + * @param serviceClass service class + * @param <T> type of service + * @return service implementation + * @throws org.onlab.osgi.ServiceNotFoundException if service is unavailable + */ + <T> T get(Class<T> serviceClass); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverProvider.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverProvider.java new file mode 100644 index 00000000..354d93e9 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverProvider.java @@ -0,0 +1,34 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import java.util.Set; + +/** + * Represents entity capable of providing device drivers and their + * behaviours. + */ +public interface DriverProvider { + + /** + * Returns the set of driver types and behaviour implementations to be + * made available by this provider. + * + * @return set of driver types and their behaviours + */ + Set<Driver> getDrivers(); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverResolver.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverResolver.java new file mode 100644 index 00000000..094c710f --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverResolver.java @@ -0,0 +1,34 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Entity capable of resolving a driver using its name. + */ +public interface DriverResolver { + + /** + * Returns the specified driver. + * + * @param driverName driver name + * @return driver + * @throws org.onlab.util.ItemNotFoundException if driver with the given + * name is not found + */ + Driver getDriver(String driverName); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverService.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverService.java new file mode 100644 index 00000000..1a74255b --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/DriverService.java @@ -0,0 +1,83 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import org.onosproject.net.DeviceId; + +import java.util.Set; + +/** + * Service for obtaining drivers and driver behaviour implementations. + */ +public interface DriverService extends DriverResolver { + + /** + * Returns the overall set of drivers being provided. + * + * @return provided drivers + */ + Set<Driver> getDrivers(); + + /** + * Returns the set of drivers which support the specified behaviour. + * + * @param withBehaviour behaviour class to query by + * @return provided drivers + */ + Set<Driver> getDrivers(Class<? extends Behaviour> withBehaviour); + + /** + * Returns the driver that matches the specified primordial device + * discovery information. + * + * @param mfr device manufacturer + * @param hw device hardware name/version + * @param sw device software version + * @return driver or null of no matching one is found + */ + Driver getDriver(String mfr, String hw, String sw); + + /** + * Returns the driver for the specified device. If the device carries + * {@code driver} annotation, its value is used to look-up the driver. + * Otherwise, the device manufacturer, hardware and software version + * attributes are used to look-up the driver. First using their literal + * values and if no driver is found, using ERE matching against the + * driver manufacturer, hardware and software version fields. + * + * @param deviceId device identifier + * @return driver or null of no matching one is found + * @throws org.onlab.util.ItemNotFoundException if device or driver for it + * are not found + */ + Driver getDriver(DeviceId deviceId); + + /** + * Creates a new driver handler for interacting with the specified device. + * The driver is looked-up using the same semantics as + * {@link #getDriver(DeviceId)} method. + * + * @param deviceId device identifier + * @param credentials optional login credentials in string form + * @return driver handler + * @throws org.onlab.util.ItemNotFoundException if device or driver for it + * are not found + */ + DriverHandler createHandler(DeviceId deviceId, String... credentials); + + // TODO: Devise a mechanism for retaining DriverData for devices + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/HandlerBehaviour.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/HandlerBehaviour.java new file mode 100644 index 00000000..b5771ac1 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/HandlerBehaviour.java @@ -0,0 +1,38 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +/** + * Representation of a facet of device behaviour that can be used to interact + * with a device (in context of {@link org.onosproject.net.driver.DriverHandler}). + */ +public interface HandlerBehaviour extends Behaviour { + + /** + * Returns the driver handler context on which this behaviour operates. + * + * @return driver handler context + */ + DriverHandler handler(); + + /** + * Sets the driver handler context for this behaviour. + * + * @param handler driver handler + */ + void setHandler(DriverHandler handler); + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/XmlDriverLoader.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/XmlDriverLoader.java new file mode 100644 index 00000000..fc5e04a1 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/XmlDriverLoader.java @@ -0,0 +1,176 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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.onosproject.net.driver; + +import com.google.common.collect.ImmutableMap; +import com.google.common.collect.Maps; +import org.apache.commons.configuration.ConfigurationException; +import org.apache.commons.configuration.HierarchicalConfiguration; +import org.apache.commons.configuration.XMLConfiguration; + +import java.io.IOException; +import java.io.InputStream; +import java.util.Map; + +/** + * Utility capable of reading driver configuration XML resources and producing + * a device driver provider as a result. + * <p> + * The drivers stream structure is as follows: + * </p> + * <pre> + * <drivers> + * <driver name=“...” [manufacturer="..." hwVersion="..." swVersion="..."]> + * <behaviour api="..." impl="..."/> + * ... + * [<property name=“key”>value</key>] + * ... + * </driver> + * ... + * </drivers> + * </pre> + */ +public class XmlDriverLoader { + + private static final String DRIVERS = "drivers"; + private static final String DRIVER = "driver"; + + private static final String BEHAVIOUR = "behaviour"; + private static final String PROPERTY = "property"; + + private static final String NAME = "[@name]"; + private static final String EXTENDS = "[@extends]"; + private static final String MFG = "[@manufacturer]"; + private static final String HW = "[@hwVersion]"; + private static final String SW = "[@swVersion]"; + private static final String API = "[@api]"; + private static final String IMPL = "[@impl]"; + + private final ClassLoader classLoader; + + private Map<String, Driver> drivers = Maps.newHashMap(); + + /** + * Creates a new driver loader capable of loading drivers from the supplied + * class loader. + * + * @param classLoader class loader to use + */ + public XmlDriverLoader(ClassLoader classLoader) { + this.classLoader = classLoader; + } + + /** + * Loads the specified drivers resource as an XML stream and parses it to + * produce a ready-to-register driver provider. + * + * @param driversStream stream containing the drivers definitions + * @param resolver driver resolver + * @return driver provider + * @throws java.io.IOException if issues are encountered reading the stream + * or parsing the driver definitions within + */ + public DefaultDriverProvider loadDrivers(InputStream driversStream, + DriverResolver resolver) throws IOException { + try { + XMLConfiguration cfg = new XMLConfiguration(); + cfg.setRootElementName(DRIVERS); + cfg.setAttributeSplittingDisabled(true); + + cfg.load(driversStream); + return loadDrivers(cfg, resolver); + } catch (ConfigurationException e) { + throw new IOException("Unable to load drivers", e); + } + } + + /** + * Loads a driver provider from the supplied hierarchical configuration. + * + * @param driversCfg hierarchical configuration containing the drivers definitions + * @param resolver driver resolver + * @return driver provider + */ + public DefaultDriverProvider loadDrivers(HierarchicalConfiguration driversCfg, + DriverResolver resolver) { + DefaultDriverProvider provider = new DefaultDriverProvider(); + for (HierarchicalConfiguration cfg : driversCfg.configurationsAt(DRIVER)) { + DefaultDriver driver = loadDriver(cfg, resolver); + drivers.put(driver.name(), driver); + provider.addDriver(driver); + } + drivers.clear(); + return provider; + } + + /** + * Loads a driver from the supplied hierarchical configuration. + * + * @param driverCfg hierarchical configuration containing the driver definition + * @param resolver driver resolver + * @return driver + */ + public DefaultDriver loadDriver(HierarchicalConfiguration driverCfg, + DriverResolver resolver) { + String name = driverCfg.getString(NAME); + String parentName = driverCfg.getString(EXTENDS); + String manufacturer = driverCfg.getString(MFG, ""); + String hwVersion = driverCfg.getString(HW, ""); + String swVersion = driverCfg.getString(SW, ""); + + Driver parent = parentName != null ? resolve(parentName, resolver) : null; + return new DefaultDriver(name, parent, manufacturer, hwVersion, swVersion, + parseBehaviours(driverCfg), + parseProperties(driverCfg)); + } + + // Resolves the driver by name locally at first and then using the specified resolver. + private Driver resolve(String parentName, DriverResolver resolver) { + Driver driver = drivers.get(parentName); + return driver != null ? driver : + (resolver != null ? resolver.getDriver(parentName) : null); + } + + // Parses the behaviours section. + private Map<Class<? extends Behaviour>, Class<? extends Behaviour>> + parseBehaviours(HierarchicalConfiguration driverCfg) { + ImmutableMap.Builder<Class<? extends Behaviour>, + Class<? extends Behaviour>> behaviours = ImmutableMap.builder(); + for (HierarchicalConfiguration b : driverCfg.configurationsAt(BEHAVIOUR)) { + behaviours.put(getClass(b.getString(API)), getClass(b.getString(IMPL))); + } + return behaviours.build(); + } + + // Parses the properties section. + private Map<String, String> parseProperties(HierarchicalConfiguration driverCfg) { + ImmutableMap.Builder<String, String> properties = ImmutableMap.builder(); + for (HierarchicalConfiguration b : driverCfg.configurationsAt(PROPERTY)) { + properties.put(b.getString(NAME), (String) b.getRootNode().getValue()); + } + return properties.build(); + } + + @SuppressWarnings("unchecked") + private Class<? extends Behaviour> getClass(String className) { + try { + return (Class<? extends Behaviour>) classLoader.loadClass(className); + } catch (ClassNotFoundException e) { + throw new IllegalArgumentException("Unable to load class " + className, e); + } + } + +} diff --git a/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/package-info.java b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/package-info.java new file mode 100644 index 00000000..fbc39a89 --- /dev/null +++ b/framework/src/onos/core/api/src/main/java/org/onosproject/net/driver/package-info.java @@ -0,0 +1,68 @@ +/* + * Copyright 2015 Open Networking Laboratory + * + * Licensed 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. + */ + +/** + * Set of facilities to allow the platform to be extended with + * device specific behaviours and to allow modeling device behaviours while + * hiding details of specific device driver implementations. + * <p> + * {@link org.onosproject.net.driver.Driver} is a representation of a + * specific family of devices supports set of + * {@link org.onosproject.net.driver.Behaviour behaviour classes}. Default + * implementation is provided by the platform and allows DriverProviders to + * add different behaviour implementations via DriverService. + * </p> + * <p> + * {@link org.onosproject.net.driver.DriverData} is a container for data + * learned about a device. It is associated with a specific + * {@link org.onosproject.net.driver.Driver} + * and provides set of {@link org.onosproject.net.driver.Behaviour behaviours} + * for talking about a device. A default + * implementation provided by platform and has mutable key/value store for use by + * implementations of {@link org.onosproject.net.driver.Behaviour behaviours}. + * </p> + * <p> + * {@link org.onosproject.net.driver.DriverHandler} is an entity used as a + * context to interact with a device. It has a peer + * {@link org.onosproject.net.driver.DriverData} instance, which is used to + * store information learned about a device. It also + * provides set of {@link org.onosproject.net.driver.Behaviour behaviours} + * for talking to a device. + * </p> + * <p> + * {@link org.onosproject.net.driver.DriverService} can be used to query the + * inventory of device drivers and their behaviours, while the + * {@link org.onosproject.net.driver.DriverAdminService} allows adding/removing + * drivers and managing behaviour implementations. + * {@link org.onosproject.net.driver.DriverProvider} is an entity capable + * of add/removing drivers and supplying and managing behaviour + * implementations. A default implementation is provided by the framework along + * with a {@link org.onosproject.net.driver.XmlDriverLoader loader utility} to + * create a driver provider from an XML file structured as follows: + * <pre> + * <drivers> + * <driver name=“...” [manufacturer="..." hwVersion="..." swVersion="..."]> + * <behaviour api="..." impl="..."/> + * ... + * [<property name=“key”>value</key>] + * ... + * </driver> + * ... + * </drivers> + * </pre> + * + */ +package org.onosproject.net.driver;
\ No newline at end of file |