Jetspeed Proposal: 0003
LAST MODIFIED: $Date$
AUTHOR:  burton@apache.org
STATUS: 
TITLE: PSML.next
DEPENDS: 0001

********************************************************************************
* WARNING:  THIS DOCUMENT WAS INITIALLY A PROPOSAL.  PLEASE CHECK THE DATE AS  *
* THIS MAY HAVE BECOME OLD.                                                    * 
********************************************************************************

<NOTE>
This is a document in process.  Please do not comment on this :)

TODO:  
    - Should we have a CapabilityMapRegistry?
        - should we require a 
            <capability-map ref="CAPABILITY_MAP_REGISTRY_NAME"/>
            
            to be the only way to access a capability-map?

    - Move OCS content feeds into jetspeed-config
    - Should we obsolete JetspeedResources.properties and just rely on
      jetspeed-config for everything.?
    
</NOTE>

<background>
I initially discussed a PSML revision in an e-mail named 'Is PSML wrong?'.  The 
goals of this e-mail was to provide:

- automatic portal configuration not dependent on mime-type
    - you could use the same PSML across WAP and HTML.  
- keep as much info within XML as possible.

Thinking over the situation I no longer think this was possible.  I was hoping
that a different approach to the whole problem might solve the following items,
but it doesn't appear that way.

</background>

It is becoming apparent that our PSML implementation isn't perfect.  The 
following items have become a problem or are new proposed features.

These are not all my ideas.  They were distilled from public discussion on the
jetspeed@list.working-dogs mailing list with significant contribution from:

   Raphaël Luta <luta.raphael@networks.vivendi.net>
   Neeme Praks  <neeme@one.lv>
   
********************************************************************************
1. PortletControls and PortletControllers aren't registered in a central location
********************************************************************************

Change <entry> into <portlet-entry>.  Also add <portlet-control-entry> and 
<portlet-controller-entry>.  Misc code changes within the core.

See ./docs/proposals/0001.txt within CVS for a full proposal.

Peer classes will be in org.apache.jetspeed.xml.peer.registrymarkup and will be:

PortletEntry
PortletControlEntry
PortletControllerEntry

********************************************************************************
2. We can't handle user profiles.
********************************************************************************

Currently we have a 'default' profile.  This mechanism needs to be enhanced so 
that we can provide alternative 

We need to setup a similar mechanism to item 4.  In order to handle profiles we
can register them within the PortletRegistry (so they can be accessed easily) 

<profile-registry>

    <!--
    media-type specifies the media (and hence CapabilityMap to base off of)
    
    name is associated with the profile-entry
    -->

    <default-profile-entry 
        media-type="html-lite"     
        ref="default-html-lite"/>

    <default-profile-entry 
        media-type="html"          
        ref="default-html"/>

    <default-profile-entry 
        media-type="wml"           
        ref="default-wml"/>

    <profile-entry name="default-html-lite">
        <url>/content/profiles/default-html-lite.psml</url>
        <metainfo>
            <title>Default HTML Lite Profile</title>
            <description>
                Profile for browsers that don't support high level HTML
            </description>
        </metainfo>
    </profile-entry>

    <profile-entry name="default-html-lite">
        <url>/content/profiles/default-html-lite.psml</url>
        <metainfo>
            <title>Default HTML Profile</title>
            <description>
                Profile for uplevel browsers (Mozilla, IE).
            </description>
        </metainfo>
    </profile-entry>
    
    <profile-entry name="sports">
        <url>/content/profiles/sports.psml</url>
        <metainfo>
            <title>Sports</title>
            <description>
                ESPN and various sports channels.
            </description>
        </metainfo>
    </profile-entry>
    
</profile-registry>

When complete.  'default-html.psml' should become the default Profile for the
html media type.

********************************************************************************
3. We don't have explicit PortletSets within PSML.  We are just using <portlets>
********************************************************************************

All references to <portlets> should change to <portlet-set> in both user and
registry PSML.  The root document node needs to change from <portlets> to 
<psml> in user PSML.  This maps correctly to the Java object PortletSet.

The <portlets> element in registry psml will be removed.

User PSML code will start with <psml> and contain one root <portlet-set>

 <psml>
         <!-- whatever PSML markup not currrently defined -->
         <portlet-set>
                 <!-- standard PSML content -->
         </portlet-set>
 </psml>


********************************************************************************
4. The PSML is media and mime-type specific
********************************************************************************
    
Use the Profiler mechanism to provide a mechanism to choose PSML based on 
MediaTypes (see item 7) and filename mapping.  (a default profile will be used 
if they don't exist) 

If user connects to Jetspeed with a client of text/html then we can serve 
up:

/content/users/burton/psml/text/html/html-lite/default.psml

if they connect with WAP we could hand them:

/content/users/burton/psml/text/vnd.wap.wml/wml/default.psml

********************************************************************************
5. There is no way to uniquely identify a PortletSet
********************************************************************************

In default.psml we will provide some basic names.  In autogenerated PSML we
will use GUIDs.  Since the names won't conflict with the GUIDs (as long as this
remains clear and documented) we should be fine and won't have any conflicts.

This will also allow the Customizer to correctly identify which PortletSet a 
user wants to add/remove/etc a Portlet from.

********************************************************************************
6.  Rework the Registry mechanism.
********************************************************************************

Build out a new package: org.apache.jetspeed.registry.

There should be a base interface: Registry with multiple implementations:

- PortletRegistry
- PortletControlRegistry
- PortletControllerRegistry
- ProfileRegistry
- CapabilityMapRegistry
- MediaTypeRegistry ( see item 7 - MediaType registration )

********************************************************************************
7.  MediaType registration
********************************************************************************

(NOTE:.  There is a slight overlap with Cocoon functionality.  Merge this into 
Cocoon 2.0 -> Jetspeed 2.0 when the time is right) 

It is important to allow other publication mechanisms besides MimeType 
publication.

- The text/html MimeType can mean many things.  Table support, JavaScript, etc.
  It is important to have multiple HTML media types registered.  Some thin 
  clients can render HTML but only if they don't use Javascript or HTML 4.0 
  features (tables, CSS, etc).
  
- The text/xml MimeType is even more confusing.  There can be multiple 
  namespaces under this mime type that we should publish to.
  
  
There should also be a mechanism for Jetspeed to bypass the automatic MediaType
guessing provided by UserAgent.  An HTML web browser ( Mozilla ) might actually
want to request XML for an XSLT transformation.  In this case Jetspeed should 
accept a /media-type/ocs (for Open Content Syndication namespace) URL.

The registration process allow the following markup

<!--
Registers all media types available within Jetspeed.
-->
<media-type-registry>

    <media-type-entry name="html-lite">
        <capability-map ref="html-lite">
        <metainfo>
            ...
        </metainfo>
    </media-type-entry>

</media-type-registry>

********************************************************************************
7.  Rework of Jetspeed configuration
********************************************************************************

Jetspeed's current registry.psml (PortletRegistry XML) needs to be a subset of
a higher configuration mechanism.

We need a new markup that can hold multiple sections and can be enhanced in the 
future.  What is needed is a 'jetspeed-config' schema:

<jetspeed-config>

    <portlet-registry>
        
        <!--CONSIDER XINCLUDE HERE --> 
     
    </portlet-registry>

    <media-type-registry>

    </media-type-registry>    
    
    
    <!--
    Add the ability for future sections here.
    -->
    
</jetspeed-config>