# Copyright 2011-2014 Splunk, Inc.
#
# 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.
from __future__ import absolute_import
from . search_command import SearchCommand
class GeneratingCommand(SearchCommand):
""" Generates events based on command arguments.
Generating commands receive no input and must be the first command on a
pipeline. By default Splunk will run your command locally on a search head:
.. code-block:: python
@Configuration()
class SomeGeneratingCommand(GeneratingCommand)
You can change the default behavior by configuring your generating command
for event streaming:
.. code-block:: python
@Configuration(streaming=True)
class SomeGeneratingCommand(GeneratingCommand)
...
Splunk will then run your command locally on a search head and/or remotely
on one or more indexers.
You can tell Splunk to run your streaming-enabled generating command locally
on a search head, never remotely on indexers:
.. code-block:: python
@Configuration(local=True, streaming=True)
class SomeGeneratingCommand(GeneratingCommand)
...
If your generating command produces event records in time order, you must
tell Splunk to ensure correct behavior:
.. code-block:: python
@Configuration(generates_timeorder=True)
class SomeGeneratingCommand(GeneratingCommand)
...
:ivar input_header: :class:`InputHeader`: Collection representing the input
header associated with this command invocation.
:ivar messages: :class:`MessagesHeader`: Collection representing the output
messages header associated with this command invocation.
"""
#region Methods
def generate(self):
""" A generator that yields records to the Splunk processing pipeline
You must override this method.
"""
raise NotImplementedError('GeneratingCommand.generate(self)')
def _execute(self, operation, reader, writer):
for record in operation():
writer.writerow(record)
return
def _prepare(self, argv, input_file):
ConfigurationSettings = type(self).ConfigurationSettings
argv = argv[2:]
return ConfigurationSettings, self.generate, argv, 'ANY'
#endregion
#region Types
class ConfigurationSettings(SearchCommand.ConfigurationSettings):
""" Represents the configuration settings for a
:code:`GeneratingCommand` class
"""
#region Properties
@property
def generating(self):
""" Signals that this command generates new events.
Fixed: :const:`True`
"""
return True
@property
def generates_timeorder(self):
""" Specifies whether this command generates events in descending
time order.
Default: :const:`False`
"""
return type(self)._generates_timeorder
_generates_timeorder = False
@property
def local(self):
""" Specifies whether this command should only be run on the search
head.
This setting is used to override Splunk's default policy for running
streamable search commands. See the `streaming` configuration
setting.
Default: :const:`False`
"""
return type(self)._local
_local = False
@property
def retainsevents(self):
""" Specifies whether this command retains _raw events or transforms
them.
Default: :const:`False`
"""
return type(self)._retainsevents
_retainsevents = True
@property
def streaming(self):
""" Specifies that this command is streamable.
By default streamable search commands may be run on the search head
or one or more indexers, depending on performance and scheduling
considerations. This behavior may be overridden by setting
:code:`local=True`. This forces a streamable command to be run on the
search head.
Fixed: :const:`True`
"""
return True
#endregion
#region Methods
@classmethod
def fix_up(cls, command):
""" Verifies :code:`command` class structure.
"""
if command.generate == GeneratingCommand.generate:
raise AttributeError('No GeneratingCommand.generate override')
return
#endregion
#endregion