

                ------------------------------
                NIS Service Provider for JNDI
                ------------------------------


1.0 INTRODUCTION
----------------

NIS is Network Information Service. It is the network-wide system
database used by Solaris and other Unix(TM)-based operating system for
storing information related to users, machines and network services.

The NIS service provider implements the DirContext interface.  You can
use this provider with JNDI in order to access NIS service.  The
provider presents the data in NIS maps as JNDI DirContext and
Attribute objects using the IETF document
draft-howard-nis-schema-01.txt.


2.0 CONFORMANCE
---------------

The NIS service provider for JNDI supports Version 2 of the NIS
protocol. It does not support any of the ancillary protocols (such as
those for updating password or public keys).

The IETF document draft-howard-nis-schema-01.txt describes the mapping
of NIS map entries to X.500/LDAP-style entries.  The NIS service
provider uses this mapping to present the data it obtains from the NIS
service.

The NIS provider supports the standard NIS maps using the mapping
described in the IETF draft. Nonstandard maps can be accessed as well,
but their entries are not parsed into separate attributes.


3.0 ENVIRONMENT PROPERTIES
--------------------------

The following JNDI environment properties are relevant for the NIS
service provider:

java.naming.factory.initial

    This environment property is used to select the NIS provider;
    it's not actually used by the provider itself. It specifies the
    class name of the initial context factory for the provider.

    For example:

	java.naming.factory.initial=com.sun.jndi.nis.NISCtxFactory

    If this environment property is not set then the provider cannot
    start.

java.naming.provider.url

    Specifies NIS server information. The valid formats of the 
    URL expected by the NIS service provider are:

	nis://<hostname>/<domainname>
	nis:///<domainname>
	nis:/<domainname>
	nis:<domainname>

    where <hostname> specifies a host name or IP address of
    the server offering NIS service for the NIS domain <domainname>.
    If <hostname> is not specified, the NIS provider broadcasts
    on the local subnet for a server.  If none is found, JNDI methods
    that use the provider will fail.

    For example, 

        java.naming.provider.url=nis://megasvr/eng.widget.com

    this URL will cause the provider to contact the server 'megasrv'
    to access the NIS service for the NIS domain 'eng.widget.com'.

    If this environment property is not set, or if <hostname> is
    not found or does not serve the NIS domain <domainname>,
    JNDI calls that use the provider will fail.


4.0 TYPES OF CONTEXTS AND HOW OBJECTS ARE NAMED
-----------------------------------------------

There are three types of contexts in the NIS provider:
    -  initial context
    -  "map-list" context
    -  map context

In the initial context, there are three names: system, user, host.
"system" is bound to the map-list context, which contains a list of
the maps found in the NIS service.  You can name a map using its full
map name (e.g. "passwd.byname") or using its alias (e.g. "passwd").
Standard maps that contain the same information but using different
keys are from the JNDI perspective the same context.  For example,
both "passwd.byname" and "passby.byuid" point to the same context.

Only standard NIS maps have aliases. Nonstandard maps must be named
using their full map name as they appear on the server.

user is a shortcut for "system/passwd.byname".

host is a shortcut for "system/hosts.byname".

Each "map" context presents the contents of a single NIS map.  To name
an entry within a map, use the primary key for the "primary" map.
(e.g. "system/passwd/jsmith" names the passwd entry for the username
"jsmith").

The attributes of entries in a map have String values as specified in
draft-howard-nis-schema-01.txt.  The entries of each map (including
those not described in draft-howard-nis-schema-01.txt) have the
attributes "cn", "nisMapName", and "nisMapEntry", the definitions of
which are in draft-howard-nis-schema-01.txt.

The use of NIS URLs in the initial context is currently not supported
(e.g. you can't say
	ictx.list("nis://ypserver/eng.widget.com/system");
).


5.0 API MAPPINGS
----------------

The NIS protocol does not support updates and hence all the JNDI
update-related methods are not supported.  DirContext methods are
mapped onto NIS operations as follows.

addToEnvironment()
    NOTE: This method is currently not supported.

bind()
    This method is not supported because the NIS protocol does not
    support updates.

close()
    Releases any internal data structures used.

composeName()
    Concatenates two names.

createSubcontext()
    This method is not supported because the NIS protocol does not
    support updates.

destroySubcontext()
    This method is not supported because the NIS protocol does not
    support updates.

getAttributes()
    Only entries in map contexts have attributes. The contents of
    the NIS entry named is mapped to the attributes according to 
    draft-howard-nis-schema-01.txt. Each entry always contain the
    following three attributes: cn, nisMapName, nisMapEntry.
    Therefore, the contents of an entry from a nonstandard map
    or one that does not have a schema defined in
    draft-howard-nis-schema-01.txt can be accessed using these
    attributes.

getEnvironment()
    NOTE: This method is currently not supported.

getNameParser()
    Returns a name parser for flat names.

getSchema()
    NOTE: This method is currently not supported. In the future,
    it will return schema information as described by
    draft-howard-nis-schema-01.txt.

getSchemaClassDefinition()
    NOTE: This method is currently not supported. In the future,
    it will return schema information as described by
    draft-howard-nis-schema-01.txt.

lookup()
lookupLink()
    lookup() on a map returns a context that can be used to list it.
    lookup() on a map entry currently just returns the entry itself
    (a string). In the future, it will use 
    NamingManager.getObjectInstance() so objects can be returned.
    lookupLink() just calls lookup().

list()
listBindings()
    A list on the "system" context returns a list of the maps
    served by the NIS server. A list on an NIS map returns
    a list of entries in that map.

modifyAttributes()
    This method is not supported because the NIS protocol does not
    support updates.

removeFromEnvironment()
    NOTE: This method is currently not supported.

rebind()
    This method is not supported because the NIS protocol does not
    support updates.

rename()
    This method is not supported because the NIS protocol does not
    support updates.

search()
    search() currently only works for contexts that correspond
    to NIS maps. Furthermore, the forms of search that accepts a 
    string filter is currently not supported.

unbind()
    This method is not supported because the NIS protocol does not
    support updates.
