Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include Page
spaceKeyGrouper
pageTitleNavigation

Panel
borderColor#ccc
bgColor#FcFEFF
titleColorwhite
bgColor#FcFEFF
titleBGColor#00a400

 These topics are discussed in the "Grouper Web Services" training series.

Grouper Web Services

Gliffy Diagram
sizeL
namewsOverview
pagePin3
Children Display

Introduction

Grouper web services (grouper-ws) is a J2EE web application which exposes common Grouper business logic through SOAP and REST.  See Web Services FAQ. and architectural diagram.

...

  1. Understand the object model.  All grouper-ws services are operations based on simple data structures.  The structures support Strings, ints, arrays, and structure references.
    1. Core web service API
    2. Example structure (only "getters" and "setters" are applicable properties)
    3. Each operation has many samples (authmated captures, versioned, and up to date).  Here is an example
    4. Most options has a sensible default (e.g. MemberFilter defaults to All members)
    5. Lookup objects in various (consistent) ways.  e.g. to delete a group, you can pass the name or uuid of the group.
  2. Decide if you are using SOAP or REST (this is real REST, not Axis HTTP/XML)
    1. Both SOAP and REST support the same API
  3. Inside SOAP and REST, each operation has two levels of complexity, the normal one, and the Lite one.
    1. Normal operation: can usually be batched (support a list of inputs, e.g. add multiple groups at once), supports complex inputs (arrays or structures)
    2. Lite operation: supports only inputs of scalars (no structures, no arrays... only Strings, ints, etc).  In REST this also means that the request can be sent via query string only
  4. If SOAP:
    1. Implement based on WSDL.  Note, you cant get the 1.4 WSDL out of a 2.0 server, since it has backwards compatible changes from 1.5 and 1.6.  You could get this 1.4 WSDL from SVN though...
    1. Note, if your servlet is not grouperWs (e.g. grouper-ws) then adjust accordingly.
    2. There is a sample Java client with sample calls
  1. If REST:
    1. Decide what format you want to send and receive data.  grouper-ws supports XHTML, XML, and JSON, as well as query strings for input (in URL or message body)
    2. For example, in the URL you can set the content type you want back:
Code Block

/grouper-ws/servicesRest/xml/v2_1_000/groups/aStem%3AaGroup/members/10021368
/grouper-ws/servicesRest/json/v2_1_000/groups/aStem%3AaGroup/members/10021368
/grouper-ws/servicesRest/xhtml/v2_1_000/groups/aStem%3AaGroup/members/10021368

...

Add a new servlet filter mapping in the web.xml

Code Block

<filter-mapping>
    <filter-name>Grouper logging filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Set the filter logger to log at debug level

Code Block

log4j.logger.edu.internet2.middleware.grouper.ws.j2ee.ServletFilterLogger = DEBUG

You will see log entries like this

Code Block

2012-05-03 09:13:18,575: [http-8088-1] DEBUG ServletFilterLogger.logStuff(98) -  - IP: 127.0.0.1, url: /grouperWs/servicesRest/v2_1_001/groups/aStem%3AaGroup/members, queryString: null, method: PUT, content-type: text/x-json; charset=UTF-8
request params:
request body: {"WsRestAddMemberRequest":{"actAsSubjectLookup":{"subjectId":"GrouperSystem"},"replaceAllExisting":"F","subjectLookups":[{"subjectId":"10021368"},{"subjectId":"10039438"}]}}
respone headers: (note, not all headers captured, and not in this order)
X-Grouper-resultCode: SUCCESS
X-Grouper-success: T
X-Grouper-resultCode2: NONE
HTTP/1.1 201
Content-Type: text/x-json; charset=UTF-8
response: {"WsAddMemberResults":{"responseMetadata":{"millis":"237","serverVersion":"2.1.1"},"resultMetadata":{"resultCode":"SUCCESS","resultMessage":"Success for: clientVersion: 2.1.1, wsGroupLookup: WsGroupLookup[pitGroups=[],groupName=aStem:aGroup], subjectLookups: Array size: 2: [0]: WsSubjectLookup[subjectId=10021368]\n[1]: WsSubjectLookup[subjectId=10039438]\n\n, replaceAllExisting: false, actAsSubject: WsSubjectLookup[subjectId=GrouperSystem], fieldName: null, txType: NONE, includeGroupDetail: false, includeSubjectDetail: false, subjectAttributeNames: null\n, params: null\n, disabledDate: null, enabledDate: null","success":"T"},"results":[{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10021368","name":"10021368","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}},{"resultMetadata":{"resultCode":"SUCCESS_ALREADY_EXISTED","success":"T"},"wsSubject":{"id":"10039438","name":"10039438","resultCode":"SUCCESS","sourceId":"jdbc","success":"T"}}],"wsGroupAssigned":{"description":"a group description","displayExtension":"a group","displayName":"a stem:a group","extension":"aGroup","name":"aStem:aGroup","typeOfGroup":"group","uuid":"d9094e4a7c6e4f399d7e1489c875b9f0"}}}

...

See the always available client for more info on this slide

Children pages

Children Display

To do's (post 1.6.0)

  1. add logging filter
  2. fix javadoc warnings
  3. look into axis2 1.5, see if error fixed, see if samples/wsdl changes
  4. add move subject service
  5. improve auto-toString methods in resultMessage
  6. look at acegi
  7. add ip source filtering to grouper

...