Design Considerations
When designing the actions for an adapter, it is important to keep the model consistent when at all possible. Consistency allows a user who is familiar with one adapter to learn to use new adapters in very little time. In the following suggested action patterns that should be considered, XXX represents the name of an adapter or connected system, and YYY represents the name of an object type (e.g., User, Group), and "system" is used generically to refer to the connected system, protocol, or API the adapter is targeting. It is expected that some systems will require adaptation from the model specified here, but is recommended that the model be followed as closely as is practical for a given system.
openXXXConnection(…)
Opens a connection or session.
Used with systems, protocols, or API's that are connection or session based (e.g. LDAP, JDBC)
Input Properties:
(whatever is required to form a connection/session to the system.
Returns:
an object that represents the connection or session if successful, null or undefined otherwise
the returned object should have a no argument close() method and be registered for cleanup
closeXXXConnection(connection)
Closes a connection opened with openXXXConnection()
Input Properties:
connection - the connection to close
Returns:
true if successful, false otherwise
unregisters the connection object from cleanup
defineXXXConnection(…)
Defines an object that holds the information necessary to communicate with
Used with systems that are not connection or session based but still need more than one piece of information in order to communicate with the system
Input Properties:
(whatever is required to form a communicate with the system.
Returns:
an object that encapsulates the input properties, null or undefined otherwise
Generic Object Type actions (used for systems that have a large and or extensible schema and all object types are dealt with generically by the protocol or API, e.g. LDAP, JDBC)
getXXXRecord(connection, objectType, id)
Gets a single record from the connected system
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to get
this input property is only needed if the system requires it
id - the system specific unique id of the target object
Returns:
the record for id if successful, null or undefined otherwise
getXXXRecords(connection, objectType, filter, limit)
Gets a list of records from the system
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to get
this input property is only needed if the system requires it or may be encoded in filter in some cases
filter - (optional: default all objects) system specific filter specification selecting which objects to get
some systems may not support this functionality
often useful to also accept a record that serves as an an example of what objects to get
limit - (optional: default no limit) the maximum number of records to get
some systems may not support this
Returns:
a (possibly empty) Array of records
saveXXXRecord(connection, objectType, record)
Creates or updates an object in the system.
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to save
this input property is only needed if the system requires it or may be encoded in the record in some cases
record - the record representing the object to create or the fields to update
if system generates the unique id
a record without a unique id field in the record should cause a create
a record with a unique id field should cause an update
if the system uses user generated ids
object is created if there no existing object with the specified unique id
object is updated if there is an existing object with the specified unique id
when updating, should only update fields that are specified in the record (note that a field is still considered specified if it present but has no values)
Returns:
a copy of the new or updated object record (MUST if the system generates the unique id) -OR-
true if the create/update was successful, false otherwise
deleteXXXRecord(connection, objectType, id)
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to delete
this input property is only needed if the system requires it
id - the system specific unique id of the target object
Returns:
true if the deletion was successful, false otherwise
renameXXXRecord(connection, objectType, id, newName)
Renames an object in the system
Doesn't make sense for some systems, may be combined with moveXXXRecord for others
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to delete
this input property is only needed if the system requires it
id - the system specific unique id of the target object
newLocation - the system specific unique id of the target object
Returns:
true if the rename was successful, false otherwise
moveXXXRecord(connection, objectType, id, newlocation)
Moves an object in the system
Doesn't make sense for some systems, may be combined with renameXXXRecord for others
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to delete
this input property is only needed if the system requires it
id - the system specific unique id of the target object
newLocation - the system specific unique id of the target object
Returns:
true if the rename was successful, false otherwise
openXXXRecordIterator (connection, objectType, filter)
Opens an iterator over the specified objectType in the system
Input Properties:
connection - connection object created by openXXXConnection or defineXXXConnection
objectType - the type of object to delete
this input property is only needed if the system requires it
filter - (optional: default all objects) system specific filter specification selecting which objects to get
some systems may not support this functionality
often useful to also accept a record that serves as an an example of what objects to get
Returns:
XXXRecordIterator object, which should be iterable both using additional methods and through an ECMAScript for each statement
hasNextXXXRecord (iterator)
Checks to see if any more records exist in the system for this iterator
Input Properties:
iterator: XXXRecordIterator object returned by openXXXRecordIterator
Returns:
true if there are more records, false if there are not
getNextXXXRecord (iterator)
Retrieves the next Record object from the system
Input Properties:
iterator: XXXRecordIterator object returned by openXXXRecordIterator
Returns:
Either the next Record object, or null if no more Record objects exist
closeXXXRecordIterator (iterator)
Closes any connections opened by iterator, and resets the iterator object
Input Properties:
iterator: XXXRecordIterator object returned by openXXXRecordIterator
Returns:
true if successful, false otherwise
Specific Object Type actions (used for systems that have a relatively fixed schema and/or each object type handled differently by the protocol or API)
Rather than the above listed generic actions, it is also reasonable to implement a set of actions for each object type, with the object type encoded in the name of the action (in place of “Record:) rather than being specified as an input parameter or being encoded in the record, e.g. getXXXUser() and getXXXGroup() instead of getXXXRecord().