Index: /waeup/branches/ulif-rewrite/src/waeup/university/certificatecontainer.txt
===================================================================
--- /waeup/branches/ulif-rewrite/src/waeup/university/certificatecontainer.txt	(revision 4367)
+++ /waeup/branches/ulif-rewrite/src/waeup/university/certificatecontainer.txt	(revision 4367)
@@ -0,0 +1,155 @@
+:mod:`waeup.university.certificatecontainer` -- Certificate containers
+**********************************************************************
+
+.. module:: waeup.university.certificatecontainer
+
+Containers for certificates.
+
+:Test-Layer: unit
+
+Because this module makes use of components registered with the Zope
+Component Architecture (ZCA), we first have to grok the `waeup`
+package if we want to deploy it. This happens automatically in
+real-world use:
+
+    >>> import grok
+    >>> grok.testing.grok('waeup')
+
+Content Classes (models and containers)
+=======================================
+
+:class:`CertificateContainer`
+-----------------------------
+
+.. class:: CertificateContainer()
+
+   Create a certificate container instance.
+
+   .. attribute:: grok.implements(ICertificateContainer)
+
+   .. attribute:: grok.require('waeup.manageUniversity')
+
+   :class:`CertificateContainer` instances are instances of
+   :class:`grok.Container` that hold and manage instances of
+   :class:`waeup.university.certificate.Certificate`.
+
+     >>> from waeup.university.certificatecontainer import CertificateContainer
+     >>> mycontainer = CertificateContainer()
+     >>> mycontainer
+     <waeup.university.certificatecontainer.CertificateContainer object at 0x...>
+
+   Certificate containers provide `ICertificateContainer`:
+
+     >>> from waeup.interfaces import ICertificateContainer
+     >>> ICertificateContainer.providedBy(mycontainer)
+     True
+
+   We can be sure, that the full interface is supported by the
+   CertificateContainer class:
+
+     >>> from zope.interface.verify import verifyClass
+     >>> verifyClass(ICertificateContainer, CertificateContainer)
+     True
+
+   As normal ``grok.Container``, :class:`CertificateContainer` instances
+   can be used like dicts:
+
+     >>> list(mycontainer.keys())
+     []
+
+   .. method:: addCertificate(certificate)
+
+      Add a certificate.
+
+      *certificate* must be an instance of
+      :class:`waeup.university.certificate.Certificate`:
+
+        >>> from waeup.university.certificatecontainer import (
+        ...   CertificateContainer)
+        >>> mycontainer = CertificateContainer()
+        >>> mycontainer.addCertificate('blah')
+        Traceback (most recent call last):
+        ...
+        TypeError: CertificateContainers contain only ICertificate instances
+
+      The key of added items is the ``code`` attribute:
+
+        >>> from waeup.university.certificate import Certificate
+        >>> mycertificate = Certificate(code='CERTIFICATE1')
+        >>> mycontainer.addCertificate(mycertificate)
+        >>> list(mycontainer.keys())
+        [u'CERTIFICATE1']
+
+   .. method:: clear()
+
+      Remove all contained certificates:
+
+        >>> len(mycontainer.items())
+        1
+
+        >>> mycontainer.clear()
+        >>> len(mycontainer.items())
+        0
+
+Utilities
+=========
+
+:class:`CertificateContainerFactory`
+------------------------------------
+
+.. class:: CertificateContainerFactory()
+
+   .. attribute:: grok.name(u'waeup.CertificateContainer')
+
+   .. attribute:: grok.implements(IFactory)
+
+   A named utility to deliver new instances of :class:`CertificateContainer`
+   without the need to import the implementation before:
+
+     >>> from zope.component import createObject
+     >>> mycertificatecontainer = createObject(u'waeup.CertificateContainer')
+     >>> mycertificatecontainer
+     <waeup.university.certificatecontainer.CertificateContainer object at 0x...>
+
+   The factory complies with the specifications from the
+   :class:`IFactory` insterface:
+
+     >>> from zope.interface.verify import verifyClass
+     >>> from zope.component.interfaces import IFactory
+     >>> from waeup.university.certificatecontainer import (
+     ...   CertificateContainerFactory)
+     >>> verifyClass(IFactory, CertificateContainerFactory)
+     True
+
+   This means also, that we can get the interfaces of the created
+   object from the factory:
+
+     >>> certificatecontainer_factory = CertificateContainerFactory()
+     >>> certificatecontainer_factory.getInterfaces()
+     <implementedBy waeup.university.certificatecontainer.CertificateContainer>
+
+
+Examples
+========
+
+Getting a certificate container
+-------------------------------
+
+We can easily create `CertificateContainers`:
+
+    >>> from waeup.university.certificatecontainer import CertificateContainer
+    >>> mycontainer = CertificateContainer()
+
+
+Another way to get a certificate container -- without importing the
+class -- is via factories. We registered a factory for certificate
+containers under the name ``waeup.CertificateContainer``. Now we can
+ask for an object by calling the appropriate factory:
+
+    >>> from zope.component import createObject
+    >>> createObject(u'waeup.CertificateContainer')
+    <waeup.university.certificatecontainer.CertificateContainer object at 0x...>
+
+This way we get a thing that implements ICertificateContainer without
+imports or similar.
+
