Java SDK

The Unizo Java SDK provides a robust and type-safe way to interact with the Unizo API from Java applications. It supports Java 8+ and includes comprehensive documentation and examples.

Installation

Maven

<dependency>
    <groupId>com.unizo</groupId>
    <artifactId>unizo-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.unizo:unizo-sdk:1.0.0'

SBT

libraryDependencies += "com.unizo" % "unizo-sdk" % "1.0.0"

Basic Setup

import com.unizo.UnizoClient;
import com.unizo.config.UnizoConfig;

public class Main {
    public static void main(String[] args) {
        UnizoClient client = new UnizoClient.Builder()
            .apiKey("your-api-key")
            .environment(UnizoConfig.Environment.PRODUCTION)
            .build();
    }
}

Configuration Options

import com.unizo.UnizoClient;
import com.unizo.config.UnizoConfig;
import com.unizo.config.RetryPolicy;
import java.time.Duration;

UnizoClient client = new UnizoClient.Builder()
    .apiKey("your-api-key")
    .environment(UnizoConfig.Environment.PRODUCTION)
    .baseUrl("https://api.unizo.com")
    .timeout(Duration.ofSeconds(30))
    .userAgent("MyApp/1.0.0")
    .retryPolicy(RetryPolicy.builder()
        .maxAttempts(3)
        .initialDelay(Duration.ofSeconds(1))
        .maxDelay(Duration.ofSeconds(10))
        .backoffMultiplier(2.0)
        .build())
    .debug(false)
    .build();

Authentication

API Key Authentication

// Set during initialization
UnizoClient client = new UnizoClient.Builder()
    .apiKey("your-api-key")
    .build();

// Or set later
client.setApiKey("your-api-key");

// Using system property
System.setProperty("unizo.api.key", "your-api-key");
UnizoClient client = new UnizoClient.Builder()
    .apiKey(System.getProperty("unizo.api.key"))
    .build();

Bearer Token Authentication

// For user-specific operations
UnizoClient client = new UnizoClient.Builder()
    .bearerToken("user-access-token")
    .build();

// Dynamic token updates
client.setBearerToken("new-access-token");

Usage Examples

Identity Management

import com.unizo.model.Identity;
import com.unizo.model.UpdateIdentityRequest;
import com.unizo.exception.UnizoException;
import java.util.HashMap;
import java.util.Map;

try {
    // Get user identity
    Identity identity = client.identity().get();
    System.out.println("User ID: " + identity.getId());
    System.out.println("Email: " + identity.getEmail());
    
    // Update user profile
    Map<String, Object> metadata = new HashMap<>();
    metadata.put("department", "Engineering");
    metadata.put("role", "Senior Developer");
    
    UpdateIdentityRequest updateRequest = UpdateIdentityRequest.builder()
        .name("John Doe")
        .email("john@example.com")
        .metadata(metadata)
        .build();
    
    Identity updatedIdentity = client.identity().update(updateRequest);
    
} catch (UnizoException e) {
    System.err.println("Error: " + e.getMessage());
    System.err.println("Status Code: " + e.getStatusCode());
}

Source Code Management

import com.unizo.model.Repository;
import com.unizo.model.Webhook;
import com.unizo.model.CreateWebhookRequest;
import com.unizo.model.WebhookEvent;
import com.unizo.model.ListRepositoriesRequest;
import com.unizo.model.PaginatedResponse;
import java.util.Arrays;

// List repositories
ListRepositoriesRequest listRequest = ListRepositoriesRequest.builder()
    .page(1)
    .limit(50)
    .provider("github")
    .build();

PaginatedResponse<Repository> repositories = client.sourceCode()
    .repositories()
    .list(listRequest);

repositories.getData().forEach(repo -> 
    System.out.println("Repository: " + repo.getName() + " (" + repo.getUrl() + ")")
);

// Get repository details
Repository repo = client.sourceCode()
    .repositories()
    .get("repo-id");

System.out.println("Repository stats: " + repo.getStats());

// Create webhook
CreateWebhookRequest webhookRequest = CreateWebhookRequest.builder()
    .repositoryId("repo-id")
    .url("https://your-app.com/webhooks/source-code")
    .events(Arrays.asList(WebhookEvent.PUSH, WebhookEvent.PULL_REQUEST))
    .secret("webhook-secret")
    .build();

Webhook webhook = client.sourceCode()
    .webhooks()
    .create(webhookRequest);

Ticketing System

import com.unizo.model.Ticket;
import com.unizo.model.CreateTicketRequest;
import com.unizo.model.UpdateTicketRequest;
import com.unizo.model.ListTicketsRequest;
import com.unizo.model.TicketPriority;
import com.unizo.model.TicketStatus;
import com.unizo.model.Comment;
import java.time.Instant;
import java.time.temporal.ChronoUnit;
import java.util.Arrays;
import java.util.Collections;

// Create a ticket
CreateTicketRequest createRequest = CreateTicketRequest.builder()
    .title("Bug Report: Login Issues")
    .description("Users are experiencing login failures after the latest update")
    .priority(TicketPriority.HIGH)
    .assignee("user-id")
    .tags(Arrays.asList("bug", "login", "urgent"))
    .dueDate(Instant.now().plus(3, ChronoUnit.DAYS))
    .build();

Ticket ticket = client.ticketing().tickets().create(createRequest);
System.out.println("Created ticket: " + ticket.getId());

// List tickets with filtering
ListTicketsRequest listRequest = ListTicketsRequest.builder()
    .status(TicketStatus.OPEN)
    .priority(TicketPriority.HIGH)
    .assignee("current-user")
    .page(1)
    .limit(25)
    .createdAfter(Instant.now().minus(7, ChronoUnit.DAYS))
    .build();

PaginatedResponse<Ticket> tickets = client.ticketing().tickets().list(listRequest);
System.out.println("Found " + tickets.getTotal() + " tickets");

// Update ticket
Comment comment = Comment.builder()
    .text("Started investigating the issue")
    .author("developer-id")
    .timestamp(Instant.now())
    .build();

UpdateTicketRequest updateRequest = UpdateTicketRequest.builder()
    .status(TicketStatus.IN_PROGRESS)
    .comments(Collections.singletonList(comment))
    .build();

Ticket updatedTicket = client.ticketing().tickets().update("ticket-id", updateRequest);

Communications

import com.unizo.model.EmailRequest;
import com.unizo.model.EmailResult;
import com.unizo.model.SmsRequest;
import com.unizo.model.SmsResult;
import com.unizo.model.Attachment;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

// Send email with template
Map<String, Object> variables = new HashMap<>();
variables.put("user_name", "John Doe");
variables.put("activation_link", "https://app.unizo.com/activate/token");

Attachment attachment = Attachment.builder()
    .filename("welcome_guide.pdf")
    .content("PDF content as byte array".getBytes())
    .contentType("application/pdf")
    .build();

EmailRequest emailRequest = EmailRequest.builder()
    .to(Arrays.asList("user@example.com"))
    .subject("Welcome to Unizo")
    .template("welcome-template")
    .variables(variables)
    .attachments(Arrays.asList(attachment))
    .build();

EmailResult emailResult = client.communications().email().send(emailRequest);
System.out.println("Email sent: " + emailResult.getMessageId());

// Send SMS
SmsRequest smsRequest = SmsRequest.builder()
    .to("+1234567890")
    .message("Your verification code is: 123456")
    .senderId("UNIZO")
    .build();

SmsResult smsResult = client.communications().sms().send(smsRequest);
System.out.println("SMS sent: " + smsResult.getMessageId());

Incident Management

import com.unizo.model.Incident;
import com.unizo.model.CreateIncidentRequest;
import com.unizo.model.UpdateIncidentRequest;
import com.unizo.model.ListIncidentsRequest;
import com.unizo.model.IncidentSeverity;
import com.unizo.model.IncidentStatus;
import com.unizo.model.TimelineEvent;
import java.time.Instant;
import java.util.Arrays;
import java.util.Collections;

// Create incident
CreateIncidentRequest createRequest = CreateIncidentRequest.builder()
    .title("API Service Degradation")
    .description("Response times increased by 200% across all endpoints")
    .severity(IncidentSeverity.MAJOR)
    .status(IncidentStatus.INVESTIGATING)
    .services(Arrays.asList("api-gateway", "database", "cache"))
    .affectedUsers(1500)
    .build();

Incident incident = client.incidents().create(createRequest);
System.out.println("Created incident: " + incident.getId());

// List active incidents
ListIncidentsRequest listRequest = ListIncidentsRequest.builder()
    .status(Arrays.asList(IncidentStatus.OPEN, IncidentStatus.INVESTIGATING))
    .severity(Arrays.asList(IncidentSeverity.CRITICAL, IncidentSeverity.MAJOR))
    .build();

PaginatedResponse<Incident> activeIncidents = client.incidents().list(listRequest);

// Update incident with timeline
TimelineEvent timelineEvent = TimelineEvent.builder()
    .timestamp(Instant.now())
    .event("Issue resolved")
    .description("Database performance restored to normal levels")
    .build();

UpdateIncidentRequest updateRequest = UpdateIncidentRequest.builder()
    .status(IncidentStatus.RESOLVED)
    .resolution("Scaled up database instances and optimized queries")
    .timeline(Collections.singletonList(timelineEvent))
    .build();

client.incidents().update("incident-id", updateRequest);

Error Handling

Exception Types

import com.unizo.exception.*;

try {
    Identity identity = client.identity().get();
} catch (ValidationException e) {
    System.err.println("Validation error: " + e.getMessage());
    e.getFieldErrors().forEach((field, error) -> 
        System.err.println(field + ": " + error)
    );
} catch (AuthenticationException e) {
    System.err.println("Authentication failed: " + e.getMessage());
    // Handle re-authentication
} catch (RateLimitException e) {
    System.err.println("Rate limit exceeded. Retry after: " + e.getRetryAfter() + " seconds");
    // Implement backoff strategy
} catch (NotFoundException e) {
    System.err.println("Resource not found: " + e.getMessage());
} catch (ServerException e) {
    System.err.println("Server error: " + e.getMessage());
    // Log for debugging
} catch (UnizoException e) {
    System.err.println("Unizo API error: " + e.getMessage());
    System.err.println("Status code: " + e.getStatusCode());
    System.err.println("Error code: " + e.getCode());
}

Retry Mechanism

import com.unizo.config.RetryPolicy;
import java.time.Duration;
import java.util.function.Supplier;

public class RetryHelper {
    public static <T> T withRetry(Supplier<T> operation, RetryPolicy policy) {
        Exception lastException = null;
        
        for (int attempt = 1; attempt <= policy.getMaxAttempts(); attempt++) {
            try {
                return operation.get();
            } catch (RateLimitException e) {
                lastException = e;
                if (attempt < policy.getMaxAttempts()) {
                    try {
                        Thread.sleep(Duration.ofSeconds(e.getRetryAfter()).toMillis());
                    } catch (InterruptedException ie) {
                        Thread.currentThread().interrupt();
                        throw new RuntimeException("Interrupted during retry", ie);
                    }
                }
            } catch (Exception e) {
                throw e; // Don't retry for other exceptions
            }
        }
        
        throw new RuntimeException("Max retry attempts exceeded", lastException);
    }
}

// Usage
RetryPolicy retryPolicy = RetryPolicy.builder()
    .maxAttempts(3)
    .initialDelay(Duration.ofSeconds(1))
    .build();

Identity identity = RetryHelper.withRetry(
    () -> client.identity().get(),
    retryPolicy
);

Async Support (CompletableFuture)

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

public class AsyncExample {
    private final ExecutorService executor = Executors.newCachedThreadPool();
    private final UnizoClient client;
    
    public AsyncExample(UnizoClient client) {
        this.client = client;
    }
    
    public CompletableFuture<Identity> getIdentityAsync() {
        return CompletableFuture.supplyAsync(() -> {
            try {
                return client.identity().get();
            } catch (UnizoException e) {
                throw new RuntimeException(e);
            }
        }, executor);
    }
    
    public CompletableFuture<List<Ticket>> getTicketsAsync() {
        return CompletableFuture.supplyAsync(() -> {
            try {
                ListTicketsRequest request = ListTicketsRequest.builder()
                    .status(TicketStatus.OPEN)
                    .build();
                return client.ticketing().tickets().list(request).getData();
            } catch (UnizoException e) {
                throw new RuntimeException(e);
            }
        }, executor);
    }
    
    public void processUserData() {
        CompletableFuture<Identity> identityFuture = getIdentityAsync();
        CompletableFuture<List<Ticket>> ticketsFuture = getTicketsAsync();
        
        CompletableFuture.allOf(identityFuture, ticketsFuture)
            .thenAccept(v -> {
                Identity identity = identityFuture.join();
                List<Ticket> tickets = ticketsFuture.join();
                
                System.out.println("User: " + identity.getName());
                System.out.println("Open tickets: " + tickets.size());
            })
            .exceptionally(throwable -> {
                System.err.println("Error processing user data: " + throwable.getMessage());
                return null;
            });
    }
}

Webhook Handling

Spring Boot Example

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import com.unizo.webhook.WebhookValidator;
import com.fasterxml.jackson.databind.JsonNode;

@RestController
@RequestMapping("/webhooks")
public class WebhookController {
    
    private final WebhookValidator webhookValidator;
    private final String webhookSecret;
    
    public WebhookController() {
        this.webhookSecret = System.getenv("WEBHOOK_SECRET");
        this.webhookValidator = new WebhookValidator();
    }
    
    @PostMapping("/unizo")
    public ResponseEntity<String> handleWebhook(
            @RequestHeader("X-Unizo-Signature") String signature,
            @RequestBody String payload) {
        
        if (!webhookValidator.validateSignature(payload, signature, webhookSecret)) {
            return ResponseEntity.status(401).body("Invalid signature");
        }
        
        try {
            JsonNode event = objectMapper.readTree(payload);
            String eventType = event.get("type").asText();
            
            switch (eventType) {
                case "ticket.created":
                    handleTicketCreated(event.get("data"));
                    break;
                case "incident.updated":
                    handleIncidentUpdated(event.get("data"));
                    break;
                default:
                    System.out.println("Unknown event type: " + eventType);
            }
            
            return ResponseEntity.ok("OK");
        } catch (Exception e) {
            System.err.println("Error processing webhook: " + e.getMessage());
            return ResponseEntity.status(500).body("Internal server error");
        }
    }
    
    private void handleTicketCreated(JsonNode ticketData) {
        System.out.println("New ticket created: " + ticketData.get("id").asText());
        // Process ticket creation
    }
    
    private void handleIncidentUpdated(JsonNode incidentData) {
        System.out.println("Incident updated: " + incidentData.get("id").asText());
        // Process incident update
    }
}

Servlet Example

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.BufferedReader;

public class UnizoWebhookServlet extends HttpServlet {
    
    @Override
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
            throws IOException {
        
        String signature = request.getHeader("X-Unizo-Signature");
        String payload = getRequestBody(request);
        
        WebhookValidator validator = new WebhookValidator();
        if (!validator.validateSignature(payload, signature, getWebhookSecret())) {
            response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
            response.getWriter().write("Invalid signature");
            return;
        }
        
        // Process webhook event
        processWebhookEvent(payload);
        
        response.setStatus(HttpServletResponse.SC_OK);
        response.getWriter().write("OK");
    }
    
    private String getRequestBody(HttpServletRequest request) throws IOException {
        StringBuilder sb = new StringBuilder();
        try (BufferedReader reader = request.getReader()) {
            String line;
            while ((line = reader.readLine()) != null) {
                sb.append(line);
            }
        }
        return sb.toString();
    }
}

Testing

JUnit 5 Example

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.mockito.Mock;
import org.mockito.MockitoAnnotations;
import static org.mockito.Mockito.*;
import static org.junit.jupiter.api.Assertions.*;

class UnizoServiceTest {
    
    @Mock
    private UnizoClient mockClient;
    
    @Mock
    private TicketService mockTicketService;
    
    private UnizoService unizoService;
    
    @BeforeEach
    void setUp() {
        MockitoAnnotations.openMocks(this);
        when(mockClient.ticketing()).thenReturn(mock(TicketingService.class));
        when(mockClient.ticketing().tickets()).thenReturn(mockTicketService);
        unizoService = new UnizoService(mockClient);
    }
    
    @Test
    void testCreateTicket() {
        // Given
        CreateTicketRequest request = CreateTicketRequest.builder()
            .title("Test Ticket")
            .description("Test Description")
            .build();
        
        Ticket expectedTicket = Ticket.builder()
            .id("ticket-123")
            .title("Test Ticket")
            .status(TicketStatus.OPEN)
            .build();
        
        when(mockTicketService.create(request)).thenReturn(expectedTicket);
        
        // When
        Ticket result = unizoService.createTicket(request);
        
        // Then
        assertEquals("ticket-123", result.getId());
        assertEquals("Test Ticket", result.getTitle());
        verify(mockTicketService).create(request);
    }
    
    @Test
    void testCreateTicketWithValidationError() {
        // Given
        CreateTicketRequest request = CreateTicketRequest.builder()
            .title("")
            .description("Test Description")
            .build();
        
        when(mockTicketService.create(request))
            .thenThrow(new ValidationException("Title is required"));
        
        // When & Then
        assertThrows(ValidationException.class, () -> 
            unizoService.createTicket(request)
        );
    }
}

Integration Testing

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import com.github.tomakehurst.wiremock.WireMockServer;
import static com.github.tomakehurst.wiremock.client.WireMock.*;

class UnizoClientIntegrationTest {
    
    private WireMockServer wireMockServer;
    private UnizoClient client;
    
    @BeforeEach
    void setUp() {
        wireMockServer = new WireMockServer(8089);
        wireMockServer.start();
        
        client = new UnizoClient.Builder()
            .apiKey("test-api-key")
            .baseUrl("http://localhost:8089")
            .build();
    }
    
    @Test
    void testGetIdentity() {
        // Mock the API response
        wireMockServer.stubFor(get(urlEqualTo("/v1/identity"))
            .willReturn(aResponse()
                .withStatus(200)
                .withHeader("Content-Type", "application/json")
                .withBody("{\"id\":\"user-123\",\"email\":\"test@example.com\"}")));
        
        // Test the client
        Identity identity = client.identity().get();
        
        assertEquals("user-123", identity.getId());
        assertEquals("test@example.com", identity.getEmail());
    }
    
    @AfterEach
    void tearDown() {
        wireMockServer.stop();
    }
}

Spring Integration

Configuration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.beans.factory.annotation.Value;

@Configuration
public class UnizoConfig {
    
    @Value("${unizo.api.key}")
    private String apiKey;
    
    @Value("${unizo.environment:production}")
    private String environment;
    
    @Bean
    public UnizoClient unizoClient() {
        return new UnizoClient.Builder()
            .apiKey(apiKey)
            .environment(UnizoConfig.Environment.valueOf(environment.toUpperCase()))
            .build();
    }
}

Service Layer

import org.springframework.stereotype.Service;
import org.springframework.beans.factory.annotation.Autowired;

@Service
public class SupportTicketService {
    
    private final UnizoClient unizoClient;
    
    @Autowired
    public SupportTicketService(UnizoClient unizoClient) {
        this.unizoClient = unizoClient;
    }
    
    public Ticket createSupportTicket(String userEmail, String subject, String message) {
        CreateTicketRequest request = CreateTicketRequest.builder()
            .title(subject)
            .description(message)
            .priority(TicketPriority.MEDIUM)
            .metadata(Map.of("user_email", userEmail))
            .build();
        
        return unizoClient.ticketing().tickets().create(request);
    }
    
    public List<Ticket> getUserTickets(String userEmail) {
        ListTicketsRequest request = ListTicketsRequest.builder()
            .metadata(Map.of("user_email", userEmail))
            .status(TicketStatus.OPEN)
            .build();
        
        return unizoClient.ticketing().tickets().list(request).getData();
    }
}

Performance Optimization

Connection Pooling

import okhttp3.OkHttpClient;
import okhttp3.ConnectionPool;
import java.util.concurrent.TimeUnit;

OkHttpClient httpClient = new OkHttpClient.Builder()
    .connectionPool(new ConnectionPool(20, 5, TimeUnit.MINUTES))
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS)
    .build();

UnizoClient client = new UnizoClient.Builder()
    .apiKey("your-api-key")
    .httpClient(httpClient)
    .build();

Batch Operations

import java.util.List;
import java.util.Arrays;

// Batch ticket creation
List<CreateTicketRequest> ticketsData = Arrays.asList(
    CreateTicketRequest.builder().title("Issue 1").description("First issue").build(),
    CreateTicketRequest.builder().title("Issue 2").description("Second issue").build(),
    CreateTicketRequest.builder().title("Issue 3").description("Third issue").build()
);

List<Ticket> createdTickets = client.ticketing().tickets().createBatch(ticketsData);
System.out.println("Created " + createdTickets.size() + " tickets");

Logging

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class UnizoService {
    private static final Logger logger = LoggerFactory.getLogger(UnizoService.class);
    private final UnizoClient client;
    
    public UnizoService(UnizoClient client) {
        this.client = client;
    }
    
    public Ticket createTicket(CreateTicketRequest request) {
        logger.info("Creating ticket with title: {}", request.getTitle());
        
        try {
            Ticket ticket = client.ticketing().tickets().create(request);
            logger.info("Successfully created ticket with ID: {}", ticket.getId());
            return ticket;
        } catch (UnizoException e) {
            logger.error("Failed to create ticket: {}", e.getMessage(), e);
            throw e;
        }
    }
}

Resources

• GitHub Repository
• Maven Central
• Javadoc Documentation
• Example Applications
• Changelog

Support

• Create issues on GitHub
• Email: sdk-support@unizo.com
• Discord: Unizo Developers

Requirements

• Java 8+
• Maven 3.6+ or Gradle 6.0+
• Jackson 2.12+ (for JSON processing)
• OkHttp 4.9+ (for HTTP client)
• SLF4J 1.7+ (for logging)