Package io.openems.edge.common.component

Interface OpenemsComponent

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      Channel<?> _channel​(java.lang.String channelName)
      Deprecated.
      default <T extends Channel<?>>
      T      		 _getChannelAs​(OpenemsComponent.ChannelId channelId, java.lang.Class<T> type)
      Gets the Channel as the given Type.
      java.lang.String alias()
      Returns a human-readable name of this Component..
      default <T extends Channel<?>>
      T      		 channel​(ChannelId channelId)
      Returns a Channel defined by its ChannelId.
      default <T extends Channel<?>>
      T      		 channel​(java.lang.String channelName)
      Returns a Channel defined by its ChannelId string representation.
      java.util.Collection<Channel<?>> channels()
      Returns all Channels.
      default java.lang.String debugLog()
      Gets some output that is suitable for a continuous Debug log.
      org.osgi.service.component.ComponentContext getComponentContext()
      Returns the ComponentContext.
      static ModbusSlaveNatureTable getModbusSlaveNatureTable​(AccessMode accessMode)
      Used for Modbus/TCP Api Controller.
      default Level getState()
      Gets the Component State Level.
      default StateCollectorChannel getStateChannel()
      Gets the Component State-Channel.
      default boolean hasFaults()
      Does this OpenEMS Component report any Faults?
      java.lang.String id()
      Returns a unique ID for this OpenEMS component.
      boolean isEnabled()
      Returns whether this component is enabled.
      static void logDebug​(OpenemsComponent component, org.slf4j.Logger log, java.lang.String message)
      Log a debug message including the Component ID.
      static void logError​(OpenemsComponent component, org.slf4j.Logger log, java.lang.String message)
      Log a error message including the Component ID.
      static void logInfo​(OpenemsComponent component, org.slf4j.Logger log, java.lang.String message)
      Log a info message including the Component ID.
      static void logWarn​(OpenemsComponent component, org.slf4j.Logger log, java.lang.String message)
      Log a warn message including the Component ID.
      default java.lang.String serviceFactoryPid()
      Returns the Service Factory-PID.
      default java.lang.String servicePid()
      Returns the Service PID.
      static void updateConfigurationProperty​(org.osgi.service.cm.ConfigurationAdmin cm, java.lang.String pid, java.lang.String property, java.lang.Object value)
      Update a configuration property.
      static boolean updateReferenceFilter​(org.osgi.service.cm.ConfigurationAdmin cm, java.lang.String pid, java.lang.String member, java.lang.String... ids)
      Sets a target filter for a Declarative Service @Reference member.
      static boolean updateReferenceFilterRaw​(org.osgi.service.cm.ConfigurationAdmin cm, java.lang.String pid, java.lang.String member, java.lang.String filter)
      Sets a target filter for a Declarative Service @Reference member.
      static boolean validateSingleton​(org.osgi.service.cm.ConfigurationAdmin cm, java.lang.String pid, java.lang.String expectedId)
      Validates and possibly fixes the Component-ID of a Singleton.

    • Method Detail

      • id

        java.lang.String id()
        Returns a unique ID for this OpenEMS component.
        Returns:
        the unique ID

      • alias

        java.lang.String alias()
        Returns a human-readable name of this Component..
        Returns:
        the human-readable name

      • isEnabled

        boolean isEnabled()
        Returns whether this component is enabled.
        Returns:
        true if the component is enabled

      • servicePid

        default java.lang.String servicePid()
        Returns the Service PID.
        Returns:
        the OSGi Service PID

      • serviceFactoryPid

        default java.lang.String serviceFactoryPid()
        Returns the Service Factory-PID.
        Returns:
        the OSGi Service Factory-PID

      • getComponentContext

        org.osgi.service.component.ComponentContext getComponentContext()
        Returns the ComponentContext.
        Returns:
        the OSGi ComponentContext

      • _channel

        @Deprecated
Channel<?> _channel​(java.lang.String channelName)
        Deprecated.
        Returns an undefined Channel defined by its ChannelId string representation.

        Note: It is preferred to use the typed channel()-method, that's why it is marked as @Deprecated.

        Parameters:
        channelName - the Channel-ID as a string
        Returns:
        the Channel or null

      • channel

        default <T extends Channel<?>> T channel​(java.lang.String channelName)
                                  throws java.lang.IllegalArgumentException
        Returns a Channel defined by its ChannelId string representation.
        Type Parameters:
        T - the expected typed Channel
        Parameters:
        channelName - the Channel-ID as a string
        Returns:
        the Channel or throw Exception
        Throws:
        java.lang.IllegalArgumentException - on error

      • channel

        default <T extends Channel<?>> T channel​(ChannelId channelId)
                                  throws java.lang.IllegalArgumentException
        Returns a Channel defined by its ChannelId.
        Type Parameters:
        T - the Type of the Channel. See Doc.getType()
        Parameters:
        channelId - the Channel-ID
        Returns:
        the Channel
        Throws:
        java.lang.IllegalArgumentException - on error

      • channels

        java.util.Collection<Channel<?>> channels()
        Returns all Channels.
        Returns:
        a Collection of Channels

      • getStateChannel

        default StateCollectorChannel getStateChannel()
        Gets the Component State-Channel.
        Returns:
        the StateCollectorChannel

      • getState

        default Level getState()
        Gets the Component State Level.
        Returns:
        the StateCollectorChannel

      • _getChannelAs

        default <T extends Channel<?>> T _getChannelAs​(OpenemsComponent.ChannelId channelId,
                                               java.lang.Class<T> type)
        Gets the Channel as the given Type.
        Type Parameters:
        T - the expected Channel type
        Parameters:
        channelId - the Channel-ID
        type - the expected Type
        Returns:
        the Channel

      • debugLog

        default java.lang.String debugLog()
        Gets some output that is suitable for a continuous Debug log. Returns 'null' by default which causes no output.
        Returns:
        the debug log output

      • hasFaults

        default boolean hasFaults()
        Does this OpenEMS Component report any Faults?

        Evaluates all StateChannels and returns true if any Channel with Level.FAULT is set.

        Returns:
        true if there is a Fault.

      • updateReferenceFilter

        static boolean updateReferenceFilter​(org.osgi.service.cm.ConfigurationAdmin cm,
                                     java.lang.String pid,
                                     java.lang.String member,
                                     java.lang.String... ids)
        Sets a target filter for a Declarative Service @Reference member.

        Usage: 

         updateReferenceFilter(config.service_pid(), "Controllers", controllersIds);

        Generates a 'target' filter on the 'Controllers' member so, that the the expected service to be injected needs to fulfill:

        • the service must be enabled
        • the service must not have the same PID as the calling component
        • the service "id" must be one of the provided "controllersIds"
        Parameters:
        cm - a ConfigurationAdmin instance. Get one using 
                       @Reference
               ConfigurationAdmin cm;
        pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, PID filter is not added to the resulting target filter
        member - Name of the Method or Field with the Reference annotation, e.g.
        ids - Component IDs to be filtered for; for empty list, no ids are added to the target filter
        Returns:
        true if the filter was updated. You may use it to abort the activate() method.

      • updateReferenceFilterRaw

        static boolean updateReferenceFilterRaw​(org.osgi.service.cm.ConfigurationAdmin cm,
                                        java.lang.String pid,
                                        java.lang.String member,
                                        java.lang.String filter)
        Sets a target filter for a Declarative Service @Reference member.

        Use this method only if you know what you are doing. Usually you will want to use the updateReferenceFilter(ConfigurationAdmin, String, String, String...) method instead.

        Usage: 

         updateReferenceFilterRaw(config.service_pid(), "Controllers", "(enabled=true)");
        Parameters:
        cm - a ConfigurationAdmin instance. Get one using 
                       @Reference
               ConfigurationAdmin cm;
        pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, PID filter is not added to the resulting target filter
        member - Name of the Method or Field with the Reference annotation, e.g.
        filter - The filter attribute
        Returns:
        true if the filter was updated. You may use it to abort the activate() method.

      • validateSingleton

        static boolean validateSingleton​(org.osgi.service.cm.ConfigurationAdmin cm,
                                 java.lang.String pid,
                                 java.lang.String expectedId)
        Validates and possibly fixes the Component-ID of a Singleton.

        Singleton Components are allowed to live only exactly once in an OpenEMS instance. These Components are marked with an Annotation: 

         @Designate(factory = false)
        By design it is required for these Singleton Components to have a predefined Component-ID, like '_cycle', '_sum', etc. This method makes sure the Component-ID matches this predefined ID - and if not automatically adjusts it.

        Sidenote: ideally it would be possible to use the Component Annotation 

         @Component(property = { "id=_cycle" })
        for this purpose. Unfortunately this is not sufficient to have the 'id' property listed in EdgeConfig, ConfigurationAdmin, etc. This is why this workaround is required.

        Usage: 

         if (OpenemsComponent.validateSingletonComponentId(this.cm, this.serviceFactoryPid(), SINGLETON_COMPONENT_ID)) {
        return;
 }
        Parameters:
        cm - a ConfigurationAdmin instance. Get one using 
                           @Reference
                   ConfigurationAdmin cm;
        pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'; if null, Component-ID can not be updated.
        expectedId - The expected predefined Component-ID
        Returns:
        true if the ID was updated. You may use it to abort the activate() method.

      • updateConfigurationProperty

        static void updateConfigurationProperty​(org.osgi.service.cm.ConfigurationAdmin cm,
                                        java.lang.String pid,
                                        java.lang.String property,
                                        java.lang.Object value)
        Update a configuration property.

        Usage: 

         updateConfigurationProperty(cm, servicePid, "propertyName", "propertyValue");

        Parameters:
        cm - a ConfigurationAdmin instance. Get one using 
                         @Reference
                 ConfigurationAdmin cm;
        pid - PID of the calling component (use 'config.service_pid()' or '(String)prop.get(Constants.SERVICE_PID)'
        property - Name of the configuration property
        value - New configuration value

      • logDebug

        static void logDebug​(OpenemsComponent component,
                     org.slf4j.Logger log,
                     java.lang.String message)
        Log a debug message including the Component ID.
        Parameters:
        component - the OpenemsComponent
        log - the Logger instance
        message - the message

      • logInfo

        static void logInfo​(OpenemsComponent component,
                    org.slf4j.Logger log,
                    java.lang.String message)
        Log a info message including the Component ID.
        Parameters:
        component - the OpenemsComponent
        log - the Logger instance
        message - the message

      • logWarn

        static void logWarn​(OpenemsComponent component,
                    org.slf4j.Logger log,
                    java.lang.String message)
        Log a warn message including the Component ID.
        Parameters:
        component - the OpenemsComponent
        log - the Logger instance
        message - the message

      • logError

        static void logError​(OpenemsComponent component,
                     org.slf4j.Logger log,
                     java.lang.String message)
        Log a error message including the Component ID.
        Parameters:
        component - the OpenemsComponent
        log - the Logger instance
        message - the message