001/** 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved 005 * 006 * The contents of this file are subject to the terms 007 * of the Common Development and Distribution License 008 * (the License). You may not use this file except in 009 * compliance with the License. 010 * 011 * You can obtain a copy of the License at 012 * https://opensso.dev.java.net/public/CDDLv1.0.html or 013 * opensso/legal/CDDLv1.0.txt 014 * See the License for the specific language governing 015 * permission and limitations under the License. 016 * 017 * When distributing Covered Code, include this CDDL 018 * Header Notice in each file and include the License file 019 * at opensso/legal/CDDLv1.0.txt. 020 * If applicable, add the following below the CDDL Header, 021 * with the fields enclosed by brackets [] replaced by 022 * your own identifying information: 023 * "Portions Copyrighted [year] [name of copyright owner]" 024 * 025 * $Id: UMSObject.java,v 1.5 2008/06/25 05:41:46 qcheng Exp $ 026 * 027 */ 028 029package com.iplanet.ums; 030 031import java.security.Principal; 032 033import com.sun.identity.shared.debug.Debug; 034import com.iplanet.services.ldap.AttrSet; 035import com.iplanet.services.util.I18n; 036import com.iplanet.sso.SSOException; 037import com.iplanet.sso.SSOToken; 038import com.iplanet.sso.SSOTokenManager; 039 040/** 041 * UMSObject class exposes public methods that serve as the entry points to the 042 * UMS SDK. This class is used to replace the public static methods that are 043 * previously available in Session class. 044 * <p> 045 * 046 * <pre> 047 * // Previous access class with authenticated context 048 * // 049 * UMSObject.getObject( Context ctx, String guid ); 050 * UMSObject.removeObject( Context ctx, String guid ); 051 * UMSObject.logout( Context ctx ); 052 * 053 * // New API with the use of Principal interface that represents an 054 * // authenticated principal 055 * UMSObject.getObject( java.security.Principal principal, String guid ); 056 * UMSObject.removeObject(java.security.Principal principal, String guid); 057 * </pre> 058 * 059 * @supported.api 060 */ 061public class UMSObject { 062 063 public static final String UMS = "UMS"; 064 065 public static final String ENTITY = "ENTITY"; 066 067 public static final String UTIL = "UTIL"; 068 069 private static Debug debug = Debug.getInstance(IUMSConstants.UMS_DEBUG); 070 071 private static I18n i18n = I18n.getInstance(IUMSConstants.UMS_PKG); 072 073 /** 074 * Returns the persistent object of correct subclass, for the given id. 075 * The Java class to construct the persistent object is inferred from the 076 * default creation templates registered with the Template manager. 077 * 078 * @param token Authenticated principal's single sign on token. 079 * @param guid GUID identification of the object to get. 080 * @return the object read, all non operational attributes are read. 081 * @throws UMSException if there is an error while instantiating 082 * the right type of object. In addition, it propagates any 083 * exception from the datalayer. 084 * @supported.api 085 */ 086 static public PersistentObject getObject(SSOToken token, Guid guid) 087 throws UMSException { 088 return getObject(token, guid, null); 089 } 090 091 /** 092 * Returns the persistent object of correct subclass, for the given ID. The 093 * Java class to construct the persistent object is inferred from the 094 * default creation templates registered with the Template manager. 095 * 096 * @param token Authenticated principal's single sign on token. 097 * @param guid GUID identification of the object to get 098 * @param attrNames attribute names to read. 099 * @return the object read. 100 * @throws UMSException if there is an error while instantiating 101 * the right type of object. In addition, it propagates any 102 * exception from the datalayer. 103 * @supported.api 104 */ 105 static public PersistentObject getObject( 106 SSOToken token, 107 Guid guid, 108 String[] attrNames 109 ) throws UMSException { 110 Principal principal = null; 111 try { 112 SSOTokenManager.getInstance().validateToken(token); 113 } catch (SSOException se) { 114 throw new UMSException(i18n.getString(IUMSConstants.INVALID_TOKEN), 115 se); 116 } 117 try { 118 principal = token.getPrincipal(); 119 } catch (SSOException se) { 120 throw new UMSException(i18n.getString(IUMSConstants.BAD_TOKEN_HDL), 121 se); 122 } 123 return getObject(principal, guid, attrNames); 124 } 125 126 /** 127 * Removes an object identified by the given ID. 128 * 129 * @param token Authenticated principal's single sign on token. 130 * @param guid GUID identification of the object to be removed. 131 * @throws EntryNotFoundException if the entry is not found. 132 * @throws UMSException if there is an error while removing the object from 133 * persistence store 134 * @supported.api 135 */ 136 static public void removeObject(SSOToken token, Guid guid) 137 throws EntryNotFoundException, UMSException { 138 try { 139 SSOTokenManager.getInstance().validateToken(token); 140 } catch (SSOException se) { 141 throw new UMSException(i18n.getString(IUMSConstants.INVALID_TOKEN), 142 se); 143 } 144 try { 145 DataLayer.getInstance().deleteEntry(token.getPrincipal(), guid); 146 } catch (SSOException se) { 147 throw new UMSException(i18n.getString(IUMSConstants.BAD_TOKEN_HDL), 148 se); 149 } 150 } 151 152 public static PersistentObject getObject(Principal principal, Guid guid) 153 throws UMSException { 154 return getObject(principal, guid, null); 155 } 156 157 public static PersistentObject getObject(Principal principal, Guid guid, 158 String[] attrNames) throws UMSException { 159 AttrSet attrSet = null; 160 if (attrNames == null) { 161 attrSet = DataLayer.getInstance().read(principal, guid); 162 } else { 163 int length = attrNames.length; 164 String[] attrNames1 = new String[length + 1]; 165 System.arraycopy(attrNames, 0, attrNames1, 0, length); 166 attrNames1[length] = "objectclass"; 167 attrSet = DataLayer.getInstance().read(principal, guid, attrNames1); 168 } 169 String id = guid.getDn(); 170 if (id == null) { 171 String msg = i18n.getString(IUMSConstants.BAD_ID); 172 throw new IllegalArgumentException(msg); 173 } 174 Class javaClass = TemplateManager.getTemplateManager() 175 .getJavaClassForEntry(id, attrSet); 176 PersistentObject po = null; 177 try { 178 po = (PersistentObject) javaClass.newInstance(); 179 } catch (Exception e) { 180 String args[] = new String[1]; 181 args[0] = e.toString(); 182 String msg = i18n 183 .getString(IUMSConstants.NEW_INSTANCE_FAILED, args); 184 throw new UMSException(msg); 185 } 186 po.setAttrSet(attrSet); 187 po.setGuid(guid); 188 po.setPrincipal(principal); 189 return po; 190 } 191 192 /** 193 * Return a PersistentObject given an authenticated token and guid. The 194 * validity of the returned PersistentObject can not be guaranteed since the 195 * object is created in memory, not instantiated from the persistent 196 * storage. Using the PersistentObject returned from this method may result 197 * exceptions in the later part of the application if the given guid is not 198 * valid or represents an entry that does not exist. 199 * 200 * @param token 201 * Valid and authenticated token 202 * @param guid 203 * Globally unique identifier for the entity 204 * @return the PersistentObject created in memory 205 * @throws UMSException 206 * for failure to create the object 207 * 208 * @supported.api 209 */ 210 public static PersistentObject getObjectHandle(SSOToken token, Guid guid) 211 throws UMSException { 212 213 String dn = guid.getDn(); 214 if (token == null || dn == null) { 215 String msg; 216 if (token == null) { 217 msg = i18n.getString(IUMSConstants.NULL_TOKEN); 218 debug.error("UMSObject.PersistentObject: token is null"); 219 } else { 220 msg = i18n.getString(IUMSConstants.BAD_GUID); 221 debug.error("UMSObject.PersistentObject: dn is null"); 222 } 223 224 throw new UMSException(msg); 225 } 226 227 Principal principal = null; 228 try { 229 SSOTokenManager.getInstance().validateToken(token); 230 } catch (SSOException se) { 231 throw new UMSException(i18n.getString(IUMSConstants.INVALID_TOKEN), 232 se); 233 } 234 try { 235 principal = token.getPrincipal(); 236 } catch (SSOException se) { 237 throw new UMSException(i18n.getString(IUMSConstants.BAD_TOKEN_HDL), 238 se); 239 } 240 241 PersistentObject po = new PersistentObject(); 242 po.setGuid(guid); 243 po.setPrincipal(principal); 244 return po; 245 } 246 247}