#!/usr/bin/env python
# -*- coding: utf-8 -*-

# Copyright 2010 British Broadcasting Corporation and Kamaelia Contributors(1)
#
# (1) Kamaelia Contributors are listed in the AUTHORS file and at
#     http://www.kamaelia.org/AUTHORS - please extend this file,
#     not this notice.
#
# 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.
# -------------------------------------------------------------------------
"""\
================================================
Components to help build Services (EXPERIMENTAL)
================================================

These components make it easier to build and use public services, registered
with the Coordinating Assistant Tracker.

Note: These components are EXPERIMENTAL and are likely to under go substantial
change


Register Service
----------------

A function that registers specified inboxes on a component as named services
with the Coordinating Assistant Tracker (CAT). Returns the component, so can
be dropped in where you would ordinarily use a component.



Example Usage:
~~~~~~~~~~~~~~

Create and activate MyComponent instance, registering its "inbox" inbox with the
CAT as a service called "MyService"::
    
    RegisterService( MyComponent(), {"MyService":"inbox"} ).activate()
    
    

How does it work?
~~~~~~~~~~~~~~~~~

This method registers the component you provide with the CAT. It register the
inboxes on it that you specify using the names that you specify.



Subscibe To Service
-------------------

A component that connects to a public service and sends a fixed format message
to it requesting to subscribe to a set of 'things' it provides. 



Example Usage:
~~~~~~~~~~~~~~

Subscribe to a (fictional) "TV Channels Service", asking for three channels. The
tv channel data is then recorded::
    
    pipeline(
        SubscribeTo( "TV Channels Service", ["BBC ONE", "BBC TWO", "ITV"] ),
        RecordChannels(),
        ).run()

The message sent to the "TV Channels Service" will be::
    
    ("ADD", ["BBC ONE", "BBC TWO", "ITV"], ( <theSubscribeToComponent>, "inbox" ) )



How does it work?
~~~~~~~~~~~~~~~~~

Describe more detail here




Connect To Service
------------------

A component that connects to a public service. Any data you send to its inbox
gets sent to the service.



Example Usage
~~~~~~~~~~~~~
::
    
    pipeline( MyComponentThatSendMessagesToService(),
            ConnectTo("Name of service"),
            ).run()



How does it work?
~~~~~~~~~~~~~~~~~

Describe in more detail here.
"""

from Axon.AxonExceptions import ServiceAlreadyExists
from Axon.CoordinatingAssistantTracker import coordinatingassistanttracker as CAT
from Axon.Component import component
from Axon.Ipc import shutdownMicroprocess, producerFinished

def RegisterService(component, services):
    cat = CAT.getcat()